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Preface 


This manual provides users of the OpenVMS operating system with detailed 
usage and reference information about the string manipulation routines supplied 
in the STR$ facility of the Run-Time Library. 

Intended Audience 
This manual is intended for system and application programmers who write 
programs that call STR$ Run-Time Library routines. 

Document Structure 
This manual is organized into two parts as follows: 
e Part I is a tutorial, structured as follows: 


— Chapter 1 provides a brief overview of the STR$ routines and lists the 
routines and their functions. 


— Chapter 2 discusses in detail how to use the Run-Time Library STR$ 
routines. 


¢ Part II provides detailed reference information on each routine contained 
in the STR$ facility of the Run-Time Library. This information is presented 
using the documentation format described in OpenVMS Programming 
Concepts Manual. Routine descriptions appear in alphabetical order by 
routine name. 


Related Documents 


The Run-Time Library routines are documented in a series of reference manuals. 
A description of how the Run-Time Library routines are accessed and of the 
OpenVMS features and functionality available through calls to the STR$ 
Run-Time Library appear in the OpenVMS Programming Concepts Manual. 
Descriptions of other RTL facilities and their corresponding routines and usages 
are discussed in the following books: 


* Compag Portable Mathematics Library 

* OpenVMS VAX RTL Mathematics (MTH$) Manual 
* OpenVMS RTL DECtalk (DTK$) Manual? 

¢ OpenVMS RTL Library (LIB$) Manual 

* OpenVMS RTL General Purpose (OTS$) Manual 

* OpenVMS RTL Paralld Processing (PPL$) Manual? 


This manual has been archived but is available on the OpenVMS Documentation 
CD-ROM. 


* Ope@mVMS RTL Screen Managenent (SMG$) Manual 


The Guide to the POSIX Threads Library contains guidelines and reference 
information for Compag POSIX Threads2, the Compaq Multithreading Run-Time 
Library. 

The OpMVMS Calling Standard contains useful information for anyone who 
needs to call Run-Time Library routines. 


Application programmers using any programming language can refer to the Guide 
to Creating OpenVMS Modular Procedures for writing modular and reentrant 
code. 

High-level language programmers will find additional information on calling 
Run-Time Library routines in their language reference manual. Additional 
information may also be found in the language user’s guide provided with your 
OpenVMS language software. 

For a complete list and description of the manuals in the OpenVMS 
documentation set, see the OpenVMS Version 7.3 New Features and 
Documentation Overview. 


For additional information about Compaq OpenVMS products and services, access 
the Compaq website at the following location: 


http://www.openvms.compaq.com/ 


Reader’s Comments 


Compaq welcomes your comments on this manual. Please send comments to 
either of the following addresses: 
Internet openvmsdoc@compaq.com 


Mail Compaq Computer Corporation 
OSSG Documentation Group, ZK O3-4/U 08 
110 Spit Brook Rd. 
Nashua, NH 03062-2698 


How To Order Additional Documentation 
Use the following World Wide Web address to order additional documentation: 
http://www. openvms.compaq.com/ 


If you need help deciding which documentation best meets your needs, call 
800-282-6672. 


2 Compag POSIX Threads was formerly called DECthreads. 
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Conventions 


The following conventions are used in this manual: 


Ctrl/x 


PF1x 


Return 


[] 


{} 


bold text 


italic text 


UPPERCASE TEXT 


A sequence such as Ctrl/x indicates that you must hold down 
the key labeled Ctrl while you press another key or a pointing 
device button. 


A sequence such as PF 1 x indicates that you must first press 
and release the key labeled PF1 and then press and release 
another key or a pointing device button. 


In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


In the HTML version of this document, this convention appears 
as brackets, rather than a box. 


A horizontal ellipsis in examples indicates one of the following 
possibilities: 


¢ Additional optional arguments in a statement have been 
omitted. 


¢ The preceding item or items can be repeated one or more 
times. 


¢ Additional parameters, values, or other information can be 
entered. 


A vertical ellipsis indicates the omission of items from a code 
example or command format; the items are omitted because 
they are not important to the topic being discussed. 


In command format descriptions, parentheses indicate that you 
must enclose choices in parentheses if you specify more than 
one. 


In command format descriptions, brackets indicate optional 
choices. You can choose one or more items or no items. 

Do not type the brackets on the command line. However, 
you must include the brackets in the syntax for OpenVMS 
directory specifications and for a substring specification in an 
assignment statement. 


In command format descriptions, braces indicate a required 
choice of options; you must choose one of the items listed. Do 
not type the braces on the command line. 


This typeface represents the introduction of a new term. It 
also represents the name of an argument, an attribute, or a 
reason. 


Italic text indicates important information, complete titles 
of manuals, or variables. Variables include information that 
varies in system output (Internal error number), in command 
lines ((PRODUCER=name), and in command parameters in 
text (where dd represents the predefined code for the device 
type). 


Uppercase text indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 
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Monospace text 


numbers 


Monospace type indicates code examples and interactive screen 
displays. 

In the C programming language, monospace type in text 
identifies the following elements: keywords, the names 

of independently compiled external functions and files, 

syntax summaries, and references to variables or identifiers 
introduced in an example. 


A hyphen at the end of a command format description, 
command line, or code line indicates that the command or 
statement continues on the following line. 


All numbers in text are assumed to be decimal unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 
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STR$ Tutorial Section 


This part of the O(peVMS RTL String Manipulation (STR$) Manual contains a 
tutorial for the OpenVMS RTL String Manipulation (STR$) facility. 


The material is structured as follows: 


— Chapter 1 provides a brief overview of the STR$ routines and lists the 
routines and their functions. 


— Chapter 2 discusses in detail how to use the Run-Time Library STR$ 
routines. 


1 


Run-Time Library String Manipulation (STR$) 
Facility 


This chapter contains an overview of the STR$ facility and lists the routines 
and their functions. Chapter 2 explains in detail how the STR$ facility handles 
strings. The STR$ Reference Section describes all the STR$ routines. 
1.1 Overview 
The STR¢$ facility provides routines to perform the following functions: 
¢ Perform mathematical operations on strings (see Table 1-1) 
*« Compare strings (see Table 1-2) 
e« Extract and replace substrings (see Table 1-3) 
¢« Append and concatenate strings (see Table 1-4) 
* Copy strings (see Table 1-5) 
¢ Search for characters and substrings (see Table 1-6) 
¢ Free and allocate dynamic strings (see Table 1-7) 


¢ Perform miscellaneous functions on strings (See Table 1-8) 


Table 1-1 STR$ Mathematical Operation Routines 


Routine Name Function 

STR$ADD Add two decimal strings 

STR$DIVIDE Divide two decimal strings 

STR$MUL Multiply two decimal strings 
STR$RECIP Return the reciprocal of a decimal string 
STR$ROUND Round or truncate a decimal string 
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1.1 Overview 


Table 1-2. STR$ Compare Routines 


Routine Name Function 

STR$CASE_BLIND_COMPARE Compare strings without regard to case 
STR$COM PARE Compare two strings 

STR$COMPARE_EQL Compare two strings for equality 
STR$COMPARE_MULTI Compare two strings for equality using the DEC 


Multinational Character Set 


Table 1-3 STR$ Extract and Replace Routines 


Routine Name Function 

STR$ELEMENT Extract delimited element substring 
STR$LEFT Extract a substring of a string 
STR$LEN_EXTR Extract a substring of a string 
STR$POS_ EXTR Extract a substring of a string 
STR$REPLACE Replace a substring 

STR$RIGHT Extract a substring of a string 


Table 1-4 STR$ Append and Concatenate Routines 


Routine Name Function 

STR$APPEND Append a string 

STR$CONCAT Concatenate two or more strings 
STR$PREFIX Prefix a string 


Table 1-5 STR$ Copy Routines 


Routine Name Function 

STR$COPY_DX Copy a source string passed by descriptor to a 
destination string 

STR$COPY_R Copy a source string passed by reference toa 
destination string 

+STR$COPY_R_64 Copy a source string passed by reference to a 


destination string 


fAlpha specific. 
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Table 1-6 STR$ Search Routines 


1.1 Overview 


Routine Name 


Function 


STR$FIND_FIRST_IN_SET 


STR$FIND_FIRST_NOT_IN_SET 


STR$FIND_FIRST_SUBSTRING 


Find the first character in a set of characters 


Find the first character that does not occur in 
the set 


Find the first substring in the input string 


Table 1-7 STR$ Allocate and Deallocate Routines 


Routine Name 


Function 


STR$FREE1 DX 
STR$GET1_DX 
+STR$GET1_DX_64 


Free one dynamic string 
Allocate one dynamic string 
Allocate one dynamic string 


$Alpha specific. 


Table 1-8 STR$ Miscellaneous Routines 


Routine Name 


Function 


STR$ANALYZE_SDESC 
+STR$ANALYZE_SDESC_64 
STR$DUPL_CHAR 
STR$MATCH_WILD 
STR$POSITION 
STR$TRANSLATE 
STR$TRIM 

STR$UPCASE 


Analyze a string descriptor 

Analyze a string descriptor 

Duplicate character n times 

Match a wildcard specification 

Return relative position of a substring 
Translate matched characters 

Trim trailing blanks and tabs 
Convert string to all uppercase 


+Alpha specific. 


1.1.1 64-Bit Addressing Support (Alpha Only) 
On Alpha systems, the String Manipulation (STR$) routines provide 64-bit virtual 


addressing capabilities as follows: 


« All STR$ RTL routines now accept 64-bit addresses for arguments passed by 


reference. 


« All STR$ RTL routines also accept either 32-bit or 64-bit descriptors for 


arguments passed by descriptor. 


*« In some cases a new routine was added to support a 64-bit addressing or 
data capability. These routines carry the same name as the original routine 
but with a _64 suffix. In general, both versions of the routine support 64-bit 
addressing but the routine with the _64 suffix also supports additional 64-bit 
capability. The 32-bit capabilities of the original routine are unchanged. 


See the OpenVMS Programming Concepts Manual for more information about 


64-bit virtual addressing capabilities. 
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Introduction to String Manipulation (STR$) 


Routines 


This chapter explains in detail the following topics: 


Types of strings recognized by Run-Time Library routines 
Relationship of descriptor classes to string semantics 


Differences in string handling among the LIB$, OTS$, and STR¢$ facilities of 
the Run-Time Library 


Conventions for reading and writing string arguments in the Run-Time 
Library string routines 


Selection of the proper string manipulation routines 


Allocation and deallocation of dynamic string resources 


Descriptor Names and Field Names 

In this chapter and throughout this manual it is generally the practice to use 
only the main part of a descriptor name or a descriptor field name, without the 
32-bit or 64-bit prefix used in the actual code. For example, the length field is 
referred to using LENGTH rather than by mentioning both DSC$W_LENGTH 
and DSC64$Q_ LENGTH. The complete descriptor or field name, including the 
prefix, is used only when referring to one particular form of the descriptor. 


2.1 String Semantics in the Run-Time Library 


The semantics of a string refers to the conventions that determine how a string 
is stored, written, and read. The Alpha and VAX architectures support three 
string semantics: fixed length, varying length, and dynamic length. 

2.1.1 Fixed-Length Strings 
Fixed-length strings have the following attributes: 


An address 
A length 


The length of a fixed-length string is constant. It is usually initialized when 
the program is compiled or linked. After initialization, this length is read but 
never written. When a Run-Time Library routine copies a source string into a 
longer fixed-length destination string, the routine pads the destination string 
with trailing blanks. 
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When you pass a string to a Run-Time Library routine, you pass the string by 
descriptor. For a fixed-length string, the descriptor must contain this information: 


¢« The descriptor class 

¢ The data type of the string 

¢ The length of the string in bytes 

e The address of the beginning of the string 


In most cases, you do not have to construct an actual descriptor. By default, 
most OpenVMS Alpha and OpenVMS VAX languages pass strings by descriptor. 
For information about how the language you are using handles strings, see 
your language reference manual. For more information about descriptors used 
for fixed-length strings, refer to OpenVMS Programming Interfaces: Calling a 
System Routine! 


Note 


In contrast to Run-Time Library routines, system services do not 

pad output strings. For this reason, when a program calls a system 
service that returns a fixed-length string, the program should supply an 
additional argument that indicates how many bytes the system service 
actually deposited in the fixed-length buffer of the calling program. Some 
system service routines have corresponding Run-Time Library routines 
that provide the proper semantics for fixed-length, varying-length, and 
dynamic output strings. 


2.1.2 Varying-Length Strings 
Varying-length strings have the following attributes: 


¢ A current length 
e An address 
« A maximum length 


The current length, in bytes, of a varying-length string is stored in a two-byte 
field, called CURLEN, preceding the text of the string. The address of the string 
points to the beginning of this CURLEN field, not to the beginning of the string’s 
text. 


The maximum string length is a field in the string’s descriptor. This field specifies 
how much space is allocated to the string in a program. The maximum string 
length is fixed and does not change. 


The value in the CURLEN field specifies how many bytes beyond the CURLEN 
field are occupied by the string’s text. The character positions beyond this range 
are reserved for the growth of the string. Their contents are undefined. 


For example, assume a varying string whose CURLEN is 3 and whose maximum 
length is 6. If a string » ABCD’ is copied into this string, the result is ABCD’ 
and the CURLEN is changed to 4. If a string XYZ’ is now copied into the 
same varying string, the resulting string is ‘XYZ’ with a CURLEN of 3. The 
maximum length is still 6. The bytes beyond the range designated by CURLEN 
are undefined. 


Lt cee has been archived but is available on the OpenVMS Documentation 
D-ROM. 
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For varying-length strings pointed to by both 32-bit and 64-bit descriptors, 
CURLEN is a two-byte field. Because of this, the maximum length of a varying- 
length string is limited to 216 - 1, or 65,535, characters. 


2.1.3 Dynamic-Length Strings 
Dynamic-length strings have the following attributes: 


¢ A current length 
e An address pointing to the beginning of the text 


Theoretically, dynamic strings have unbounded length. However, the descriptor 
LENGTH field contains the length of the string as an unsigned value. This 
effectively limits the maximum length of the string to the maximum unsigned 
integer value this field can hold. 


For 32-bit dynamic descriptors, the LENGTH field is an unsigned value occupying 
two bytes. Because its maximum value is 2! - 1, or 65,535, the maximum length 
of a string is limited to 65,535 characters. 


On Alpha systems, the LENGTH field of a 64-bit dynamic descriptor is an 
unsigned value occupying eight bytes. Because its maximum value is 26 - 1, the 
maximum length of a string is 26 - 1 characters. 


The actual space for a dynamic-length string is allocated from heap storage by 
the Run-Time Library. When a Run-Time Library routine copies a character 
string into a dynamic string, and the currently allocated heap storage is not large 
enough to contain the string, the currently allocated storage returns to a pool of 
heap storage maintained by the string routines. Then the string routines obtain 
a new area of the correct size. As a result of this process of deallocation and 
reallocation, both the current-length field and the address portion of the string’s 
descriptor may change. Often, dynamic strings are the most convenient type to 
write. 


Note 


The Run-Time Library STR$ routines are the only routines that you 
should use to alter the length or address of a dynamic string. Do not use 
LIB$GET_VM or LIB$GET_VM_64 for this purpose. 


2.1.4 Examples 


The following examples illustrate what happens when the string ,ABCDEF” (of 
length 6) is copied into various destination strings: 


e Fixed-length string 
If ‘ABCDEF” is copied into a fixed-length string, three results are possible: 


1. If the length of the output string is greater than the length of the source 
string, the string is padded with trailing spaces. 


Length of output string 10 
Result 'RBCDEF ’ 
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2. If the length of the output string is the same as that of the input string, 
the string is simply copied with no modification. 


Length of output string 6 
Result ' ABCDEF’ 


3. If the length of the output string is less than the length of the source 
string, truncation on the right occurs. 


Length of output string 3 
Result "BBC! 


¢ Varying-length string 


If the string ’ABCDEF’ is copied into a varying-length string, two results are 
possible: 


1. If the MAXSTRLEN field of the destination is greater than or equal 
to the length of the source, the input string is written into the output 
string without modification, and the CURLEN (current length) field of the 
output string becomes 6. 


2. If the MAXSTRLEN field of the destination is less than the length of the 
source string, the source string is truncated on the right and the CURLEN 
field is rewritten to its current length. For example, if MAXSTRLEN =4, 
the resulting string contains ABCD’ and CURLEN =4. 


« Dynamiclength string 


If the string ABCDEF’” is copied into a dynamic destination string, three 
results are possible: 


1. If the length of the destination string is greater than the length of the 
source string (6), the result is a dynamic string of length 6 containing 
‘ABCDEF’. No padding takes place. The Run-Time Library may 
deallocate the string and reallocate a new string closer in length to 
the length of the source string. 


2. If the length of the destination string is less than the length of the source 
string, the result is also ABCDEF’, with a length of 6. The Run-Time 
Library deallocates the destination string and allocates a new string large 
enough to hold the 6 characters. 


3. If the destination string and source string are of equal length, a simple 
copy is done. No allocation, deallocation, or padding takes place, and the 
destination descriptor is not modified. 


2.2 Descriptor Classes and String Semantics 


A calling program passes strings to an STR$ routine by descriptor. That is, the 
argument list entry for an input or output string is actually the address of a 
string descriptor. All STR$ routines handle both 32-bit and 64-bit descriptors in 
the argument list. 


The calling program allocates a descriptor for the input string that indicates the 
string’s address and length, so that the called routine can find the string’s text 
and operate on it. The calling program also allocates a descriptor for the output 
string. In addition to length and address fields, each descriptor contains a field 
(DSC$B_CLASS or DSC64$B_ CLASS) indicating the descriptor’s class. The STR$ 
routine reads the class field to determine whether to write the output string as a 
fixed-length, varying-length, or dynamic string. 
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To determine the address and length of the data in the input string, Run- 

Time Library routines call one of the string descriptor analysis routines: 
LIB$ANALYZE SDESC, LIB$ANALYZE SDESC 64, STR$ANALYZE SDESC, or 
STR$ANALYZE_ SDESC 64. 


The STR$ routines provide a centralized facility for analyzing string descriptors, 
allowing string-handling routines to function independently of the class of the 
input string. This means that if the Run-Time Library recognizes new string 
types, only the analysis routine needs to be changed, not the string routines 
themselves. If you are writing a routine that recognizes all the string types 
recognized by the Run-Time Library, your routine should first call the appropriate 
string-descriptor analysis routine to obtain the address and length of the input 
string. 


You can also use the string descriptor analysis routines to find the length of 

a returned string. Assume that your called routine calls one of the Run-Time 
Library string-copying routines to create a new string. You now want the called 
routine to return the actual length of the new string to the calling program. The 
called routine calls one of the string-descriptor analysis routines to determine 
this length. This sequence of calls allows you to create the new string without 
knowing its ultimate length at the time it is created. 


The Run-Time Library routines recognize the following classes of string 
descriptors: 


e« Z—unspecified 

e« S—scalar, fixed-length string 
« SD—decimal scalar 

« VS—varying-length string 

« D—dynamic string 

e A—array 

« NCA—noncontiguous array 


For a detailed description of these descriptor classes and their fields, see the 
OpenVMS Calling Standard. 


Table 2-1 indicates how the Run-Time Library routines access the fields of the 
descriptor for input and output string arguments. Given the class of the string 
and the field of the descriptor, the table shows whether the routine reads, writes, 
or modifies the field. 
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Table 2-1 String Passing Techniques Used by the Run-Time Library 


String Descriptor Fields 


String Type Class Length Pointer 


Input Argument to Routines 


Input string passed by descriptor Read Read Read 


Output Argument from Routines; Called Routine Assumes the Descriptor Class 


Output string passed by descriptor, | gnored Read Read 

fixed-length 

Output string passed by descriptor, Ignored Read, can be Read, can be modified 
dynamic modified 


Output Argument from Routines; Calling Program Specifies the Descriptor Class in the Descriptor 


Output string, fixed-length— Read Read Read 
Descriptor class: S, Z, A, NCA, SD 
Output string, dynamic— Read Read, can be Read, can be modified 
Descriptor class: D modified 
Output string, varying-length— Read MAXSTRLEN is Read 
Descriptor class: VS read; CURLEN is 
modified 


2.2.1 Conventions for Reading Input String Arguments 


When a calling program passes a string as an argument to a Run-Time Library 
routine, the argument contains the address of a descriptor. The called routine 
examines the CLASS field of the descriptor to determine in which fields it can 
find the length of the string and the first byte of the string’s text. For each 
descriptor class, Table 2-2 indicates which descriptor fields the routine uses 

to locate this information. For diagrams of the descriptors, see the O(0eVMS 
Calling Standard manual. 


Table 2-2. How Run-Time Library Routines Read Strings 


Class String Length Address of First Byte of Data 
Z DSC$W_LENGTH DSC$A_POINTER 
DSC64$Q LENGTH DSC64$PQ POINTER 
S DSC$W_LENGTH DSC$A_POINTER 
DSC64$Q LENGTH DSC64$PQ POINTER 
D DSC$W_LENGTH DSC$A_POINTER 
DSC64$Q LENGTH DSC64$PQ POINTER 
A DSC$L_ARSIZE DSC$A_POINTER 
DSC64$Q_ ARSIZE DSC64$PQ POINTER 
SD DSC$W_LENGTH DSC$A_POINTER 
DSC64$Q LENGTH DSC64$PQ POINTER 
NCA DSC$L_ARSIZE DSC$A_POINTER 
DSC64$Q_ ARSIZE DSC64$PQ POINTER 


(continued on next page) 
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Table 2-2 (Cont.) How Run-Time Library Routines Read Strings 


Class String Length Address of First Byte of Data 
VS Word at DSC$A_POINTER or Value of DSC$A_POINTER +2 or 
at DSC64$PQ_ POINTER of DSC64$PQ POINTER +2 
(CURLEN field) (byte after CURLEN field) 
Note: 
e |f the descriptor class is NCA, it is assumed that the string is actually 
contiguous. 


e If the descriptor class is A or NCA, the element size is assumed to be 1 byte. 


e |f the descriptor class is A or NCA and the array being passed is 
multidimensional, you should be aware of how your language stores arrays 
(by column or by row). 


2.2.2 Semantics for Writing Output String Arguments 


Normally, Run-Time Library routines return the result of an operation in one of 
the following ways: 


¢« The called routine returns the result as a function value in RO/R1. If the 
result is too large to fit in RO/R1, it is returned as a function value in the 
first position in the argument list, and the other arguments are shifted one 
position to the right. 


e The called routine returns the result as an output argument. The calling 
program passes to the called routine an argument naming a variable in which 
the routine writes the output string. In each RTL routine, the access field of 
an output argument contains “write only”. 


The STR$ routines that produce string results use the first method to pass the 
results back to the calling program. Because a result string, by definition, does 
not fit in RO/R1, the function value from an STR$ routine is placed in the first 
position in the argument list. 


The string manipulation routines in the LIB$ and OTS$ facilities use the second 
method, returning their results as output arguments. 


For example, there are three entry points for the string-copying routine: 
LIB$SCOPY_DXDX, OTS$SCOPY_DXDX, and STR$COPY_DX. These copy 
the source string to the destination string. Their formats are as follows: 


LIB$SCOPY_DXDX(sourcestring ,destination-string) 
OTS$SCOPY_DXDX(sourcestring ,destination-string) 
STR$COPY_DX(destination-string ,source-string) 


Because the STR$ entry point places the result string in the first position, you 
can call STR$¢COPY_DX using a function reference in languages that support 

string functions. In Fortran, for example, you can use a function reference to 

invoke STR$COPY_DX in the following ways: 


CHARACTER*80 STRSCOPY_DX 
RETURN_STATUS = STRSCOPY_DX(DESTINATION_STRING, SOURCE_STRING) 


or 


DESTINATION_STRING = STRSCOPY_DX (SOURCE_STRING) 
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If you use the second form, you cannot access the return status, which is used to 
indicate truncation. 


If you use a function reference to invoke a string manipulation routine in a 
language that does not support the concept of a string function (such as MACRO, 
BLISS, and Pascal), you must place the destination string variable in the 
argument list. In Pascal, for example, you can use a function reference to invoke 
STR$COPY_DxX as follows: 


STATUS := STRSCOPY_DX(DESTINATION_STRING, SOURCE_STRING) ; 
However, the following statement results in an error: 
DESTINATION_STRING := STRSCOPY_DX (SOURCE_STRING) 


In addition to allocating a variable for the output string, the calling program 
must allocate the space for and fill in the fields of the output string descriptor at 
compile, link, or run time. High-level languages do this automatically. 


When a Run-Time Library routine returns an output string argument to the 
calling program, the argument list entry is the address of a descriptor. The 
routine determines the semantics of the output string (fixed, varying, or dynamic) 
by examining the class of the descriptor for the destination string. Given the 
class of the output string’s descriptor, Table 2-3 specifies the semantics used by 
Run-Time Library routines when writing the string. 


Table 2-3 Output String Semantics and Descriptor Classes 


Class Description Restrictions Semantics 
Z Unspecified Treated as class S. Fixed-length 
string 
S Scalar, string None. Fixed-length 
string 
D Dynamic string String length: DSC$W_LENGTH <2" (64K) Dynamic-length 
DSC64$Q_LENGTH <2” string 
A Array Array is one-dimensional (DIMCT =1). Fixed-length 
String length: DSC$L_ARSIZE <2? (64K) string 
DSC64$Q_ARSIZE <2 
Length of array elements is 1 byte (LENGTH =1). 
SD Scalar decimal The DIGITS and SCALE fields are ignored. Fixed-length 
string 
NCA Noncontiguous Array is one-dimensional (DIMCT =1). Fixed-length 
array String length: DSC$L_ARSIZE <2? (64K) string 
DSC64$Q_ARSIZE <2 
Length of array elements is 1 byte (LENGTH =1). 
Array is contiguous (S1 =LENGTH). 
VS Varying string Current length less than maximum string length. Varying-length 
(CURLEN < MAXSTRLEN < 2" (64K)) string 
When a called routine returns a string whose length cannot be determined by 
the calling routine, the calling routine should also pass an optional argument to 
contain the output length. If the output string is a fixed-length string, the length 
argument would reflect the number of characters written, not counting the fill 
characters. 
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The output length argument is useful, for instance, when your program is reading 
variable-length records. The program can read the input strings into a buffer 
that is large enough to contain the largest. When you want to perform the next 
operation on the contents of the buffer, the length argument indicates exactly 
how many characters have been read, so that the program does not need to 
manipulate the whole buffer. 


For example, LIB$GET_INPUT has the optional argument resultant-length. 
If LIB$GET_INPUT is called with a fixed-length, 5-character string as an 
argument, and the routine reads a record containing ’ABC’, then resultant- 
length has a value of 3 and the output string (‘ABC’) contains the characters 
ABC followed by two blanks. But if the routine reads a record containing the 
value *ABCDEFG’, resultant-length has a value of 5 and the output string 
is ‘ABCDE’. In either case, the calling program knows exactly how many 
characters (not counting fillers) the routine has read. 


A routine such as STR$COPY_DX does not need the length argument, because 
the calling program can determine the length of the output string. If the output 
string is dynamic, the length is the same as the input string length. If the output 
string is fixed-length, the length is the shorter of the two input lengths. 


2.3 Selecting String Manipulation Routines 


To perform a given string manipulation operation, you can often choose one of 
several routines from the Run-Time Library. The LIB$, OTS$, and STR¢$ facilities 
all contain string copying and dynamic string allocation routines. Furthermore, a 
MACRO or BLISS program can call several of these routines using either a J SB 
or CALL entry point. 


You should consider the factors discussed in the following sections when choosing 
a routine to perform the desired operation. 


2.3.1 Efficiency 


One of the major considerations in choosing among several routines is the 
efficiency of the various options. 


In general, LIB$ and STR$ routines execute more efficiently than the 
corresponding OTS$ routines. OTS$ routines usually invoke the LIB$ entry 
point to perform an operation. 


J SB entry points usually execute more efficiently than CALL entry points. 
However, a high-level language cannot explicitly access a J SB entry point. 
Further, a] SB entry point does not establish a stack frame and executes entirely 
in the environment of the calling program. This means, for instance, that the 
called routine cannot establish its own condition handler, so it cannot regain 
control if an exception occurs during execution. Also, some of the efficiency 
gained by using the] SB entry point may be lost because the calling routine must 
explicitly save all of the registers that the called routine uses. 


Some routines perform a specific operation that is a subset of a more general 
capability. These more specialized routines are usually more efficient. 

For example, if you want to join two strings together, STR$APPEND and 
STR$PREFIX are more specific, and more efficient, than STR$CONCAT. 
Similarly, STR$LEFT and STR$RIGHT are subsets of the capabilities of 
STR$POS EXTR. 
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2.3.2 Argument Passing 


The mechanism by which a routine passes or receives arguments may also help 
you to decide among several routines that perform basically the same function. 


Routines in the LIB$ and STR$ facilities pass scalar input arguments by 
reference to CALL entry points and by immediate value to J SB entry points. 
OTS$ routines pass scalar input arguments by immediate value to all entry 
points. For most high-level languages, the default passing mechanism is by 
reference. Thus, if you call a LIB$ or STR$ routine from one of these languages, 
you do not need to specify the passing mechanism for input scalar arguments. 


Some routines require you to set up and pass more arguments than others. 

For example, some use a single string descriptor, while others require separate 
arguments for the length and the address of the string. Which routine you choose 
then depends on the form of the information already available in your program. 


2.3.3 Error Handling 


Routines from the LIB$, OTS$, and STR#$ facilities handle errors in string 
copying differently: 


« LIB$ 


The LIB$ string-copying routines return a completion status. When an output 
string must be truncated and its length depends on input arguments, LIB$ 
routines consider this to be a partial success; they therefore return LIB$_ 
STRTRU instead of a severe error. This process corresponds to the convention 
of many higher-level languages, which do not consider truncation to be an 
error. 


* OTS$ 


The OTS$ string-copying routines also signal errors that are considered fatal 
(such as invalid descriptor class). In addition, the routine returns in RO the 
number of bytes in the source string that were not moved to the destination 
string. For VAX systems, this is the same as a MOVCS instruction. The 

J SB entry points for OTS$ string-copying routines also leave registers R1 
through R5 as they would be after a VAX MOVC5 instruction. See the VAX 
Architecture Reference Manual for a complete description of the MOVC5 
instruction. 


« STR$ 


The STR$ string-copying routines generally signal errors instead of returning 
a completion status. In the case of truncation errors, STR$ routines return 
an error status with a severity of WARNING (STR$ TRU). STR$ routines 
consider range errors to be qualified success. 


Table 2-4 indicates the errors and the corresponding message that each facility 
considers severe. 
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Table 2-4 Severe Errors, by Facility 


Error LIB$_ OTS$_ STR$_ 

Fatal internal error FATERRLIB FATINTERR FATINTERR 
Illegal string class INVSTRDES INVSTRDES ILLSTRCLA 
Insufficient virtual memory INSVIRMEM INSVIRMEM INSVIRMEM 


Some Run-Time Library routines require you to specify the length of a string or 
the position of a character within a string. When you refer to character positions 
in a string, the first position is 1. Given a string with length L, containing a 
substring specified by character positions M to N, the following evaluation rules 
apply: 

e IfM is less than 1, M is considered to equal 1. 

e If M is greater than L, the substring specified is the null string. 

e IfN is greater than L, N is considered to equal the length of the source string. 
e If M is greater than N, the substring specified is the null string. 

When specifying a substring of length L, the following applies: 


e IfL is less than 0, the substring specified is the null string. (A null string is 
a descriptor with zero length. A descriptor with a nonzero length and a zero 
pointer generates an error and yields unspecified results.) 


If any of these evaluation rules applies, the range error status (qualified success) 
is returned. STR$POSITION represents the exception to this convention. This 
routine returns a function value giving the character position of a substring 
within a string. If the function value is 0, the substring was not found. 


2.4 Allocating Resources for Dynamic Strings 


This section tells how to use the Run-Time Library string resource allocation 
routines. These routines allocate virtual memory for a dynamic string and place 
the address of the allocated memory in a descriptor. 


Dynamic strings may be the most convenient type to write, since you need not 
specify constant length, maximum length, or position for them. However, there 
are some restrictions on dynamic strings. 


e« They may cause program execution to be slower at run time. 
e« They require larger address space. 
e They are not supported by all OpenVMS Alpha and OpenVMS VAX languages. 


In most cases, when you call a Run-Time Library routine to manipulate dynamic 
strings, the Run-Time Library routine itself allocates the required memory for the 
string. Your program needs to allocate only the descriptors. 


For example, if you are copying a source string into a dynamic destination string, 
simply use one of the library's string-copying routines. Copy the input string 
into a dynamic string whose length and address are initialized to zero. The 
string-copying routine then allocates the space that the calling program needs. 
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However, if your program must explicitly construct or modify a dynamic string 
descriptor, it must use the Run-Time Library allocation and deallocation routines. 
This technique may be necessary, for instance, if you are constructing a string out 
of components that are not themselves in string form. Further, you can use one 
of the deallocation routines to free the dynamic string after the string resources 
are no longer needed, in order to optimize the program's use of resources. 


The Run-Time Library provides eight entry points for string resource allocation 
and deallocation, all with slightly different input arguments, calling techniques, 
or methods of indicating errors. The following tables summarize these routines 
and their functions. 


The following routines allocate a specified number of bytes of dynamic virtual 
memory to a specified string descriptor. 


Routine JSB Entry Point 
LIB$SGET1 DD LIB$SGET1 DD _R6 
LIB$SGET1DD_64 LIB$SGET1 DD_R6 
OTS$SGET1_DD OTS$SGET1_DD_R6 
STR$GET1_DX STR$GET1_DX_R4 
STR$GET1_DX_64 STR$GET1_DX_R4 


The following routines return one dynamic string area to free storage, and set the 
descriptor POINTER and LENGTH fields to zero. 


Routine JSB Entry Point 
LIB$SFREE1 DD LIB$SFREE1 DD6 
OTS$SFREE1 DD OTS$SFREE1 DD6 
STR$FREE1 DX STR$FREE1 DX_R4 


The following routines return one or more dynamic string areas to free storage, 
and set the descriptor POINTER and LENGTH fields to zero. 


Routine JSB Entry Point 
LIB$SFREEN DD LIB$SFREEN DD6 
OTS$SFREEN DD OTS$SFREEN_DD6 


When you call the dynamic string allocation routines, consider the following 
factors: 


e When your program calls a string allocation routine, it needs to allocate space 
only for the string descriptor before making the call. Your program does this 
using the statement of the particular language, either statically at compile 
time or dynamically in local stack storage or heap storage. 


e If your routine explicitly allocates dynamic string descriptors in stack storage, 
it must explicitly free the associated dynamic string areas by calling the 
LIB$SFREE1 DD, OTS$SFREE1 DD, or STR$FREE1 DX routine Then 
your routine must free the storage for the descriptor. After both areas have 
been freed, your routine can return to the calling program. If the deallocation 
is not done, the dynamic string area becomes unavailable when the RET 
instruction removes the descriptors that point to the string area. 
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e If a routine has explicitly allocated dynamic string areas, and the routine 
is then unwound by the Condition Handling Facility (CHF), the allocated 
address space cannot be referenced again. For this reason, your program 
should establish a handler that frees the associated dynamic string areas 
when the SS$ UNWIND condition is signaled. The handler can free these 
areas by calling one of the deallocation routines. This technique is especially 
important if a large amount of address space is involved, or if the routine 
allocates space within a repeating loop. 


You can call the string resource allocation routines only from user mode, at 
asynchronous system trap (AST) or non-AST level. However, be extremely careful 
if you manipulate dynamic strings at AST level. The string manipulation routines 
in the Run-Time Library do not prevent the strings that they are manipulating at 
non-AST level from being modified at AST level. 


For example, consider the case in which a string manipulation routine has 
calculated the lengths and addresses involved in a concatenation operation. This 
string manipulation routine may be interrupted by an AST. The user, at AST 
level, may write to the same string, changing its length and address. It is then 
possible to resume execution of the routine with addresses that are no longer 
allocated or string lengths that are no longer valid. For this reason, if you use 
dynamic strings at AST level, you should allocate, use, and deallocate them 
within the AST code. 


The dynamic string manipulation routines are intended for use at user mode 
only. To manipulate dynamic strings at another access mode, you should allocate 
and deallocate storage for each string at that access mode to avoid side effects. 
Link each segment of your program that runs at a different access mode with the 
/NOSYSSHR qualifier. In this way, you establish a separate copy of the string 
database for each access mode. 


2.4.1 String Zone 


All virtual memory for dynamic strings is allocated from a Run-Time Library zone 
called the string zone. 


The string zone has the following benefits: 
e Efficient memory utilization. 


e Allocation and deallocation for long strings (more than 136 bytes for a VAX 
system and more than 272 bytes for an Alpha system) is twice as fast. 


e Elimination of paging contention with the default zone by isolation of the 
string virtual memory accesses to a separate zone. A direct side effect of this 
is that corruptions caused by writing into previously freed strings no longer 
affect items allocated in the default zone, directly easing the debugging effort 
for such problems. 


Table 2-5 shows attribute values for 32-bit and 64-bit string zones. VAX systems 
have a 32-bit string zone; Alpha systems have both a 32-bit and a 64-bit string 
zone. 


Introduction to String Manipulation (STR$) Routines 2-13 


Introduction to String Manipulation (STR$) Routines 
2.4 Allocating Resources for Dynamic Strings 


2-14 


Table 2-5 String Zone Attributes 


Attribute 32-bit String Zone 64-bit String Zone 

Algorithm Quick fit Quick fit 

Number of lookaside lists 17 (short strings from 8 to 17 (short strings from 8 to 
136 bytes) 272 bytes) 

Area of initial size 4 pages 4 pages 

Area of extension size 32 pages 32 pages 

Block size 8 bytes 16 bytes 

Alignment Longword boundary Quadword boundary 

Smallest block size 16 bytes (includes boundary 32 bytes (includes boundary 
tags) tags) 

Boundary tags Boundary tags are used for Boundary tags are used for 
long strings long strings 

Page limit No page limit No page limit 

Fill on allocate No fill on allocate No fill on allocate 

Fill on free No fill on free No fill on free 
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STR$ Reference Section 


This section contains detailed descriptions of the routines in the OpenVMS RTL 
String Manipulation (STR$) facility. 
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STR$ADD 
Add Two Decimal Strings 


The Add Two Decimal Strings routine adds two decimal strings of digits. 


Format 
STR$ADD asign ,aexp ,adigits ,osign ,bexp ,bdigits ,csign ,cexp ,cdigits 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Arguments 
asign 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Sign of the first operand. The asign argument is the address of an unsigned 
longword containing this sign. A value of 0 is considered positive; a value of 1 is 
considered negative. 


aexp 
OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which adigjits is multiplied to get the absolute value of the first 
operand. The aexp argument is the address of a signed longword containing this 


exponent. 

adigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Text string of unsigned digits representing the absolute value of the first operand 
before aexp is applied. The adigits argument is the address of a descriptor 
pointing to this string. This string must be an unsigned decimal number. 


bsign 

OpenVMS usage: longword_unsigned 
type longword (unsigned) 
access: read only 
mechanism: by reference 
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Sign of the second operand. The bsign argument is the address of an unsigned 
longword containing the second operand’s sign. A value of 0 is considered positive; 
a value of 1 is considered negative. 


bexp 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which bdigits is multiplied to get the absolute value of the second 
operand. The bexp argument is the address of a signed longword containing the 
second operand'’s exponent. 


bdigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Text string of unsigned digits representing the absolute value of the second 
operand before bexp is applied. The bdigits argument is the address of a 
descriptor pointing to this string. This string must be an unsigned decimal 
number. 


csign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Sign of the result. The csign argument is the address of an unsigned longword 
containing the result’s sign. A value of 0 is considered positive; a value of 1 is 
considered negative. 


cexp 
OpenVMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 


Power of 10 by which cdigits is multiplied to get the absolute value of the result. 
The cexp argument is the address of a signed longword containing this exponent. 


cdigits 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Text string of unsigned digits representing the absolute value of the result before 
cexp is applied. The cdigits argument is the address of a descriptor pointing to 
this string. This string is an unsigned decimal number. 


Description 
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STR$ADD adds two strings of decimal numbers (a and b). Each number to be 
added is passed to STR$ADD in three arguments: 


1. xdigits—the string portion of the number 


2. xexp—the power of ten needed to obtain the absolute value of the number 


3. xsign—the sign of the number 


The value of the number x is derived by multiplying xdigits by 10*@? and 
applying xsign. Therefore, if xdigits is equal to ’2’ and xexp is equal to 3 and 
xsign is equal to 1, then the number represented in the x arguments is 2 * 102 


plus the sign, or -2000. 


The result of the addition c is also returned in those three parts. 


Condition Values Returned 


SS$ NORMAL 
STR$ TRU 


Condition Values Signaled 


LIB$_INVARG 


STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


STR$_WRONUMARG 


Routine successfully completed. 

String truncation warning. The destination 
string could not contain all the characters in the 
result string. 


Invalid argument. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$ADD could not 
allocate heap storage for a dynamic or temporary 
string. 

Wrong number of arguments. 
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100 !+ 
! This is a sample arithmetic program 
! showing the use of STRS$ADD to add 
! two decimal strings. 


!- 


ASIGNs = 1% 

AEXP% = 3% 

ADIGITSS = ‘1’ 

BSIGN%S = 0% 

BEXP% = -4% 

BDIGITSS = '2' 

CSIGNS = 0% 

CEXP% = 0% 

CDIGITS$ = '0' 

PRINT "A = "; ASIGNS; AEXP%S; ADIGITSS 

PRINT "B = "; BSIGN%S; BEXP%; BDIGITSS 

CALL STRSADD (ASIGNS, AEXP%, ADIGITSS, & 
BSIGN%, BEXP%, BDIGITSS$, & 
CSIGN%, CEXP%, CDIGITSS) 

PRINT "C = "; CSIGN%S; CEXP%; CDIGITSS 


999 END 


This BASIC example uses STR$ADD to add two decimal strings, where the 
following values apply: 


A =-1000 (ASIGN =1, AEXP =3, ADIGITS ='17) 
B =.0002 (BSIGN =0, BEXP =-4, BDIGITS =727) 


The output generated by this program is listed below; note that the decimal value 
of C equals -999.9998 (CSIGN =1, CEXP =-4, CDIGITS =’ 9999998; ). 


A=1 31 
B=0 -4 2 
C = 1 -4 9999998 
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STR$ANALYZE_SDESC 
Analyze String Descriptor 


The Analyze String Descriptor routine extracts the length and starting address of 
the data for a variety of string descriptor classes. 

Format 
STR$ANALYZE_SDESC _input-descriptor ,integer-length ,data-address 


Corresponding JSB Entry Point 
STR$ANALYZE_SDESC_R1 


Returns 


OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: write only 
mechanism: by value 


Length of the data. The return value is the same value returned to the integer- 
length argument. 
Arguments 


input-descriptor 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Input descriptor from which STR$ANALYZE SDESC extracts the length of the 
data and the address at which the data starts. The input-descriptor argument 
is the address of a descriptor pointing to the input data. 


integer-length 
OpenVMS usage: word_unsigned 


type: word (unsigned) 

access: write only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 


Length of the data; this length is extracted from the descriptor by 
STR$ANALY ZE_SDESC. The integer-length argument is the address of an 
unsigned word integer into which STR$ANALY ZE_SDESC writes the data length. 


data-address 
OpenVMS usage: address 


type longword (unsigned) 

access: write only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 
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Address of the data; this address is extracted from the descriptor by 
STR$ANALYZE_SDESC. The data-address argument is an unsigned longword 
into which STR$ANALYZE_SDESC writes the address of the data. 


Description 


STR$ANALYZE_SDESC takes as input a 32-bit descriptor argument and extracts 
from the descriptor the length of the data and the address at which the data 
starts for a variety of string descriptor classes. See LIBS$ANALYZE SDESC for a 
list of classes. 


STR$ANALYZE_SDESC returns the length of the data in the integer-length 
argument and the starting address of the data in the data-address argument. 


STR$ANALYZE_SDESC signals an error if an invalid descriptor class is found. 
Condition Values Signaled 
STR$ ILLSTRCLA IIlegal string class. The class code found in the 


class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
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STR$ Routines 
STR$ANALYZE SDESC_ 64 (Alpha only) 


STR$ANALYZE SDESC_ 64 (Alpha only) 
Analyze String Descriptor 


Format 


The Analyze String Descriptor routine extracts the length and starting address of 
the data for a variety of string descriptor classes. 


STR$ANALYZE_SDESC_64_input-descriptor ,integer-length ,data-address 
[,descriptor-type] 


Corresponding JSB Entry Point 


Returns 


Arguments 


STR$ANALYZE_SDESC_R1 
Refer to the STR$ANALYZE SDESC routine 
for information about the JSB entry point, 
STR$ANALYZE_SDESC_R1. This JSB entry point 
returns 64-bit results on Alpha systems. 


OpenVMS usage: quadword_unsigned 


type quadword (unsigned) 
access: write only 
mechanism: by value 


Length of the data. The return value is the same value returned to the integer- 
length argument. 


input-descriptor 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Input descriptor from which STR$ANALYZE_ SDESC_ 64 extracts the length 
of the data and the address at which the data starts. The input-descriptor 
argument is the address of a descriptor pointing to the input data. The input 
descriptor can be a longword (unsigned) or a quadword (unsigned). 


integer-length 
OpenVMS usage: quadword_unsigned 


type: quadword (unsigned) 

access: write only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 


Length of the data; this length is extracted from the descriptor by 

STR$ANALY ZE_SDESC_64. The integer-length argument is the address of 

an unsigned quadword integer into which STR$ANALYZE_SDESC_64 writes the 
data length. 
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STR$ Routines 
STR$ANALYZE_SDESC_ 64 (Alpha only) 


Description 


data-address 
OpenVMS usage: address 


type: quadword (unsigned) 

access: write only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 


Address of the data; this address is extracted from the descriptor by 
STR$ANALYZE_SDESC_64. The data-address argument is an unsigned 
quadword into which STR$ANALY ZE_SDESC_64 writes the address of the data. 


descriptor-type 
OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: write only 
mechanism: by reference 


Flag value indicating the type of input descriptor. The descriptor-type 
argument contains the address of an unsigned word integer to which 
STR$ANALY ZE_SDESC_64 writes a zero (0) for a 32-bit input descriptor or 
a one (1) for a 64-bit descriptor. 


This argument is optional. 


STR$ANALYZE_SDESC_64 takes as input a descriptor argument and extracts 
from the descriptor the length of the data and the address at which the data 
starts for a variety of string descriptor classes. See LIBSANALYZE SDESC 64 
for a list of classes. 


STR$ANALYZE_SDESC_ 64 returns the length of the data in the integer-length 
argument and the starting address of the data in the data-address argument. 


STR$ANALYZE_SDESC_64 signals an error if an invalid descriptor class is 
found. 


Condition Values Signaled 
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STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ Routines 
STR$SAPPEND 


STR$APPEND 
Append String 


Format 


Returns 


Arguments 


Description 


The Append String routine appends a source string to the end of a destination 
string. 


STR$APPEND destination-string ,source-string 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string to which STR$APPEND appends the source string. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. This destination string must be dynamic or varying length. 
The maximum length of the destination string for a 32-bit descriptor is 2!©—1, or 
65,535, bytes. 


On Alpha systems, the maximum length of the destination string for all 64-bit 
descriptor classes, except varying-length strings, is 2©4—1 bytes. The maximum 
length of a varying-length string is 24—1 for both 32-bit and 64-bit descriptors. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string that STR$APPEND appends to the end of the destination string. 
The source-string argument is the address of a descriptor pointing to this source 
string. 


STR$APPEND appends a source string to the end of the destination string. The 
destination string must be a dynamic string or a varying-length string. 
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STR$ Routines 
STR$APPEND 


Condition Values Returned 


SS$ NORMAL 
STR$ TRU 


Condition Values Signaled 


STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


STR$_STRTOOLON 


Example 


10 !+ 


! This example program uses 


Routine successfully completed. 

String truncation warning. The destination 
string could not contain all of the characters 
from the concatinated string. 


Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$APPEND 
could not allocate heap storage for a dynamic or 
temporary string. 

The combined lengths of the source and 
destination strings exceeded the maximum 
allowed for the destination-string descriptor. 


! STRSAPPEND to append a source 
! string to a destination string. 


!- 


CALL STRSAPPEND (DST$, SRC$) 


DSTS = 'DOG/’ 

SRCS = ‘CAT! 

PRINT "DSTS = ";DSTS 
END 


This BASIC example uses STR$APPEND to append a source string *CAT’, toa 


destination string "DOG/’. 


The output generated by this program is as follows: 


DSTS = DOG/CAT 
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STR$ Routines 
STR$CASE_BLIND_ COMPARE 


STR$CASE_BLIND_ COMPARE 
Compare Strings Without Regard to Case 


Format 


Returns 


Arguments 


Description 


The Compare Strings Without Regard to Case routine compares two input strings 
of any supported class and data type without regard to whether the alphabetic 
characters are uppercase or lowercase. 


STR$CASE_BLIND_COMPARE _first-source-string ,second-source-string 


OpenVMS usage: longword_signed 


type longword (signed) 
access: write only 
mechanism: by value 


The values returned by STR$CASE_BLIND_ COMPARE and the conditions to 
which they translate are as follows: 


Returned Value Condition 

-1 first-source-string is less than second-source-string. 

0 Both are the same (with blank fill for shorter string). 

1 first-source-string is greater than second-source- 
string. 


first-source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


First string. The first-source-string argument is the address of a descriptor 
pointing to the first string. 


second-source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Second string. The second-source-string argument is the address of a 
descriptor pointing to the second string. 


STR$CASE_ BLIND COMPARE does not distinguish between uppercase and 
lowercase characters. The contents of both strings are converted to uppercase 
before the strings are compared, but the source strings themselves are not 
changed. STR$CASE_BLIND_COMPARE uses the DEC Multinational Character 
Set. 
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STR$ Routines 
STR$CASE_BLIND_COMPARE 


Condition Value Signaled 


STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


Example 


PROGRAM CASE_BLIND (INPUT, OUTPUT); 


+} 
This program demonstrates the use of 
STRSCASE_BLIND_COMPARE. 


First, declare the external function. 
=} 
FUNCTION STRSCASE_BLIND_ COMPARE (STR1 : VARYING 
[A] OF CHAR; STR2 : VARYING [B] OF 
CHAR) : INTEGER; EXTERN; 


{ 
{ 
{ 
{ 
{ 
{ 


+} 
Declare the variables to be used in the 
main program. 


{ 
{ 
{ 
{-} 


VAR 
STRING1 : VARYING [256] OF CHAR; 
STRING2 : VARYING [256] OF CHAR; 
RET_STATUS : INTEGER; 


{+} 
{ Begin the main program. Read values for 
{ the strings to be compared. Call 
{ STRSCASE_BLIND_COMPARE. Print the 
{ result. 
{-} 
BEGIN 
WRITELN(’ENTER THE FIRST STRING: '); 
READLN (STRING1) ; 
WRITELN(’ENTER THE SECOND STRING: '); 
READLN (STRING2) ; 
RET_STATUS := STRSCASE_BLIND_COMPARE(STRING1, STRING2) ; 
WRITELN (RET_STATUS) ; 
END. 


This Pascal example shows how to call STR$¢CASE_ BLIND COMPARE to 
determine whether two strings are equal regardless of case. One example of the 
output of this program is as follows: 


$ RUN CASE_BLIND 

ENTER THE FIRST STRING: KITTEN 

ENTER THE SECOND STRING: kItTeN 
0 
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STR$SCOMPARE 


STR$COMPARE 
Compare Two Strings 


The Compare Two Strings routine compares the contents of two strings. 


Format 
STR$COMPARE | first-source-string ,second-source-string 
Returns 
OpenVMS usage: longword_signed 
type: longword integer (signed) 
access: write only 
mechanism: by value 
The values returned by STR$COMPARE and the conditions to which they 
translate are as follows: 
Returned Value Condition 
-1 first-source-string is less than second-source-string. 
0 first-source-string is equal to second-source-string. 
1 first-source-string is greater than second-source- 
string. 
Arguments 
first-source-string 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
First string. The first-source-string argument is the address of a descriptor 
pointing to the first string. 
second-source-string 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Second string. The second-source-string argument is the address of a 
descriptor pointing to the second string. 
Description 


STR$COMPARE compares two strings for the same contents. If the strings 
are unequal in length, the shorter string is considered to be filled with blanks 
to the length of the longer string before the comparison is made. This routine 
distinguishes between uppercase and lowercase alphabetic characters. 
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Condition Value Signaled 


Example 
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STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


100 EXTERNAL INTEGER FUNCTION STRSCOMPARE 
SRC1$ = ‘ABC’ 
SRC2$ = ‘BCD . 


I+ 

Note that STRSCOMPARE will treat SRC1$ as if it were the same 
length as SRC2$ for the purpose of the comparison. Thus, it 
will treat the contents of SRC1$ as ‘ABC ', However, it 
will only ‘treat’ the contents as longer; the contents of 

the source string are not actually changed. 


STRSCOMPARE (SRC1$, SRC2$) 


F I% = 1 THEN RESULTS = ’ IS GREATER THAN ’ 
IF I% = 0 THEN RESULTS = ’ IS EQUAL TO ' 
F I% = -1 THEN RESULTS = ' IS LESS THAN ' 


PRINT SRC1$; RESULTS; SRC2$ 
999 END 


This BASIC program uses STR$COMPARE to compare two strings. The output 
generated by this program is as follows: 


ABC IS LESS THAN BCD 


STR$ Routines 
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STR$COMPARE_EQL 
Compare Two Strings for Equality 


Format 


Returns 


Arguments 


The Compare Two Strings for Equality routine compares two strings to see if they 
have the same length and contents. Uppercase and lowercase characters are not 
considered equal. 


STR$COMPARE_EQL first-source-string ,second-source-string 


OpenVMS usage: longword_unsigned 


type longword (unsigned) 
access: write only 
mechanism: by value 


The values returned by STR$COMPARE and the conditions to which they 
translate are as follows: 


Returned Value Condition 

0 The length and the contents of first-source-string are 
equal to the length and contents of second-source- 
string. 

1 Either the length of first-source-string is not equal 


to the length of second-source-string, or the contents 
of first-source-string are not equal to the contents of 
second-source-string, or both. 


first-source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


First source string. The first-source-string argument is the address of a 
descriptor pointing to the first source string. 


second-source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Second source string. The second-source-string argument is the address of a 
descriptor pointing to the second source string. 


STR-17 
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STR$COMPARE_EQL 


Condition Values Signaled 


STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


Example 


PROGRAM COMPARE_EQL (INPUT, OUTPUT) ; 


+} 
This program demonstrates the use of 
STRSCOMPARE_EQL to compare two strings. 
Strings are considered equal only if they 
have the same contents and the same length. 


First, declare the external function. 
=} 
FUNCTION STRSCOMPARE_EQL(SRCISTR : VARYING 
[A] OF CHAR; SRC2STR : VARYING [B] 
OF CHAR) : INTEGER; EXTERN; 


{ Declare the variables used in the main program. 


VAR 
STRING1 : VARYING [256] OF CHAR; 
STRING2 : VARYING [256] OF CHAR; 
RET_STATUS : INTEGER; 


{+} 
{ Begin the main program. Read the strings 
{ to be compared. Call STRSCOMARE_EQL to compare 
{ the strings. Print the result. 
{-} 
BEGIN 
WRITELN(’ENTER THE FIRST STRING: '); 
READLN (STRING1) ; 
WRITELN(’ENTER THE SECOND STRING: '); 
READLN (STRING2) ; 
RET_STATUS := STRSCOMPARE_EQL(STRING1, STRING2) ; 
WRITELN (RET_STATUS) ; 
END. 


This Pascal example demonstrates the use of STR$COMPARE_EQL. A sample of 
the output generated by this program is as follows: 


$ RUN COMPARE_EQL 

ENTER THE FIRST STRING: frog 

ENTER THE SECOND STRING: Frogs 
1 
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STR$COMPARE_MULTI 
Compare Two Strings for Equality Using Multinational Character Set 


Format 


Returns 


Arguments 


The Compare Two Strings for Equality Using Multinational Character Set 
routine compares two character strings for equality using the DEC Multinational 
Character Set. 


STR$COMPARE_MULTI_first-source-string ,second-source-string [,flags-value] 
[,foreign-language] 


OpenVMS usage: longword_signed 


type: longword (signed) 
access: write only 
mechanism: by value 


The values returned by STR$COMPARE_MULTI and the conditions to which 
they translate are as follows: 


Returned Value Condition 

-1 first-source-string is less than second-source-string. 

0 Both strings are the same; the shorter string is blank 
filled. 

1 first-source-string is greater than second-source- 
string. 


first-source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


First string in the comparison. The first-source-string argument is the address 
of a descriptor pointing to the first string. 


second-source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Second string in the comparison. The second-source-string argument is the 
address of a descriptor pointing to the second string. 
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STR$COMPARE_MULTI 


Description 
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flags-value 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by value 


A single flag bit. The flags-value argument is a signed longword integer 

that contains this flag bit. The flags-value argument indicates whether the 
comparison is to be case sensitive or case blind. The default value of flags-value 
is 0, indicating a case sensitive comparison. The following table lists the meaning 
of the bit values: 


Value Meaning 

0 Uppercase and lowercase characters are not equivalent. (The 
comparison is case sensitive.) 

1 Uppercase and lowercase characters are equivalent. (The comparison is 
case blind.) 


foreign-language 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by value 


Indicator that determines the foreign language table to be used. The foreign- 
language argument is an unsigned longword that contains this foreign language 
table indicator. The default value of foreign-language is 1. The following table 
lists the value of the foreign-language argument associated with each language 
table: 


Value Language 

1 Multinational table 

2 Danish table 

3 Finnish/Swedish table 
4 German table 

5 Norwegian table 

6 Spanish table 


STR$COMPARE_MULTI compares two character strings to see whether they 
have the same contents. Two strings are “equal” if they contain the same 
characters in the same sequence, even if one of them is blank filled to a longer 
length than the other. The DEC Multinational Character Set, or foreign language 
variations of the DEC Multinational Character Set, are used in the comparison. 


See the OpenVMS |/ O User's Reference Manual for more information about the 
DEC Multinational Character Set. 


STR$ Routines 
STR$COMPARE_MULTI 


Condition Values Signaled 


STR$ ILLSTRCLA Illegal string class. Severe error. The descriptor 
of first-source-string and/or second-source- 
string contains a class code that is not supported 
by the OpenVMS calling standard. 


LIB$ INVARG Invalid argument. Severe error. 
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STR$CONCAT 


STR$CONCAT 
Concatenate Two or More Strings 


Format 


Returns 


Arguments 
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The Concatenate Two or More Strings routine concatenates all specified source 
strings into a single destination string. 


STR$CONCAT  destination-string ,source-string [,source-string...] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$CONCAT concatenates all specified source 
strings. The destination-string argument is the address of a descriptor pointing 
to this destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


First source string; STR$CONCAT requires at least one source string. The 
source-string argument is the address of a descriptor pointing to the first source 
string. The maximum number of source strings that STR$CONCAT allows is 254. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Additional source strings; STR$CONCAT requires at least one source string. The 
source-string argument is the address of a descriptor pointing to the additional 
source string. The maximum number of source strings that STR$CONCAT allows 
is 254. 


Description 


STR$ Routines 
STR$SCONCAT 


STR$CONCAT concatenates all specified source strings into a single destination 
string. The strings can be of any class and data type, provided that the length 
fields of the descriptors indicate the lengths of the strings in bytes. You must 
specify at least one source string, and you can specify up to 254 source strings. 
The maximum length of a concatenated string for a 32-bit descriptor is 2!©—1, or 
65,535, bytes. 


On Alpha systems, the maximum length of the destination string for all 64-bit 
descriptor classes, except varying-length strings, is 264—1 bytes. The maximum 
length of a varying-length string is 2!°—1 for both 32-bit and 64-bit descriptors. 


A warning status is returned if one or more input characters are not copied to the 
destination string. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. All characters in 
the input strings were copied into the destination 
string. 

STR$ TRU String truncation warning. One or more input 
characters were not copied into the destination 
string. 


Condition Values Signaled 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STRS$CONCAT 
could not allocate heap storage for a dynamic or 
temporary string. 

STR$ STRTOOLON The combined length of all the source strings 
exceeded the maximum allowed for the 
destination-string descriptor. 

STR$ WRONUMARG Wrong number of arguments. You tried to pass 
fewer than two or more than 255 arguments to 
STR$CONCAT. 
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STR$CONCAT 


Example 


10 !+ 
! This example program uses STRSCONCAT 
! to concatenate four source strings into a 
! single destination string. 
be 
EXTERNAL INTEGER FUNCTION STRSCONCAT 
STATUS = STRSCONCAT (XS, 'A’, 'B’, 'C’, 'D’) 
PRINT "X$ = ";XS$ 
END 


The output generated by this BASIC program is as follows: 


X$ = ABCD 
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STR$COPY_DX 
Copy a Source String Passed by Descriptor to a Destination String 


Format 


The Copy a Source String Passed by Descriptor to a Destination String routine 
copies a source string to a destination string. Both strings are passed by 
descriptor. 


STR$COPY_DX_ destination-string ,source-string 


Corresponding JSB Entry Point 


Returns 


Arguments 


STR$SCOPY_DX_R8 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$COPY_ DX writes the source string. 
Depending on the class of the destination string, the following actions occur: 


Descriptor Class Action 

S, Z, SD, A, NCA Copy the source string. If needed, fill space or truncate 
on the right. 

D If the area specified by the destination descriptor is 


large enough to contain the source string, copy the 
source string and set the new length in the destination 
descriptor. If the area specified is not large enough, 
return the previous space allocation (if any) and then 
dynamically allocate the amount of space needed. Copy 
the source string and set the new length and address in 
the destination descriptor. 


VS Copy the source string to the destination string up to 
the limit of the descriptor’s MAXSTRLEN field with no 
padding. Adjust the string’s current length (CURLEN) 
field to the actual number of bytes copied. 


The destination-string argument is the address of a descriptor pointing to the 
destination string. 
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STR$COPY _ 


Description 


DX 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string that STR$COPY_DxX copies into the destination string; the 
descriptor class of the source string can be unspecified, fixed length, dynamic 
length, scalar decimal, array, noncontiguous array, or varying length. The 
source-string argument is the address of a descriptor pointing to this source 
string. (See the description of LIB$ANALYZE_ SDESC for possible restrictions.) 


STR$COPY_DX copies a source string to a destination string, where both strings 
are passed by descriptor. All conditions except success and truncation are 
signaled; truncation is returned as a warning condition value. 


STR$COPY_DX passes the source string by descriptor. In addition, an equivalent 
J SB entry point is provided, with RO being the first argument (the descriptor of 
the destination string), and R1 the second (the descriptor of the source string). 


Condition Values Returned 


SS$ NORMAL Normal successful completion. All characters in 
the input string were copied to the destination 
string. 

STR$ TRU String truncation warning. The destination 


string could not contain all of the characters 
copied from the source string. 


Condition Values Signaled 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$COPY_DX 
could not allocate heap storage for a dynamic or 
temporary string. 


STR$ Routines 
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STR$COPY_R 
Copy a Source String Passed by Reference to Destination String 


Format 


The Copy a Source String Passed by Reference to a Destination String routine 
copies a source string passed by reference to a destination string passed by 
descriptor. 


STR$COPY_R_ destination-string ,word-integer-source-length ,source-string-address 


Corresponding JSB Entry Point 


Returns 


Arguments 


STRSCOPY_R_R8 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$COPY_R copies the source string. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. 


The class field determines the appropriate action. 


See the description of LIB$ANALYZE_SDESC for restrictions associated with 
specific descriptor classes. 


word-integer-source-length 
OpenVMS usage: word_unsigned 


type word (unsigned) 
access: read only 
mechanism: by reference 


Length of the source string. The word-integer-source-length argument is the 
address of an unsigned word containing the length of the source string. 


source-string-address 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by reference 


Source string that STR$COPY_R copies into the destination string. The source- 
string-address argument is the address of the source string. 
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STR$COPY _ 


Description 


R 


STR$COPY_R copies a source string passed by reference to a destination string 
passed by descriptor. All conditions except success and truncation are signaled; 
truncation is returned as a warning condition value. 


AJ SB entry point is provided, with RO being the first argument, R1 the second, 
and R2 the third. The length argument is passed in bits 15:0 of R1. 


The actions taken by STR$COPY_R depend on the descriptor class of the 
destination string. The following table describes these actions for each 
appropriate descriptor class: 


Descriptor Class 


Action 


S,Z,SD, A, NCA 


D 


VS 


Copy the source string. If needed, space fill or truncate on 
the right. 


If the area specified by the destination descriptor is large 
enough to contain the source string, copy the source string 
and set the new length in the destination descriptor. 


If the area specified is not large enough, return the previous 
space allocation, if any, and then dynamically allocate the 
amount of space needed. Copy the source string and set the 
new length and address in the destination descriptor. 

Copy source string to destination string up to the limit 

of the descriptor’s MAXSTRLEN field with no padding. 
Readjust the string’s current length (CURLEN) field to the 
actual number of bytes copied. 


Condition Values Returned 


SS$ NORMAL 


STR$ TRU 


Condition Values Signaled 
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STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Normal successful completion. All characters in 
the input string were copied to the destination 
string. 

String truncation warning. The destination 
string could not contain all of the characters 
copied from the source string. 


Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$COPY_R 
could not allocate heap storage for a dynamic or 
temporary string. 
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STR$COPY_R_64 (Alpha Only) 
Copy a Source String Passed by Reference to Destination String 


Format 


The Copy a Source String Passed by Reference to a Destination String routine 
copies a source string passed by reference to a destination string passed by 
descriptor. 


STR$COPY_R_64_  destination-string ,quad-integer-source-length 
,source-string-address 


Corresponding JSB Entry Point 


Returns 


Arguments 


STRSCOPY_R_R8 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$¢COPY_R_64 copies the source string. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. 


The class field determines the appropriate action. 


See the description of LIB$ANALYZE_SDESC for restrictions associated with 
specific descriptor classes. 


quad-integer-source-length 
OpenVMS usage: quadword_unsigned 


type: quadword (unsigned) 
access: read only 
mechanism: by reference 


Length of the source string. The quad-integer-source-length argument is the 
address of an unsigned quadword containing the length of the source string. 


source-string-address 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by reference 


Source string that STR$COPY_R_64 copies into the destination string. The 
source-string-address argument is the address of the source string. 
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STR$COPY_R_64 (Alpha Only) 


Description 


STR$COPY_R_64 copies a source string passed by reference to a destination 
string passed by descriptor. All conditions except success and truncation are 
signaled; truncation is returned as a warning condition value. 


AJ SB entry point is provided, with RO being the first argument, R1 the second, 
and R2 the third. The length argument is passed in bits 15:0 of R1. 


The actions taken by STR$COPY_R_64 depend on the descriptor class of 
the destination string. The following table describes these actions for each 


appropriate descriptor class: 


Descriptor Class 


S,Z,SD, A, NCA 


D 


VS 


Copy the source string. If needed, space fill or truncate on 


If the area specified by the destination descriptor is large 
enough to contain the source string, copy the source string 
and set the new length in the destination descriptor. 


If the area specified is not large enough, return the previous 
space allocation, if any, and then dynamically allocate the 
amount of space needed. Copy the source string and set the 
new length and address in the destination descriptor. 

Copy source string to destination string up to the limit 

of the descriptor’s MAXSTRLEN field with no padding. 
Readjust the string’s current length (CURLEN) field to the 
actual number of bytes copied. 


Condition Values Returned 


SS$ NORMAL 


STR$ TRU 


Condition Values Signaled 
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STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Normal successful completion. All characters in 
the input string were copied to the destination 
string. 

String truncation warning. The destination 
string could not contain all of the characters 
copied from the source string. 


Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$COPY_ R_64 
could not allocate heap storage for a dynamic or 
temporary string. 
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STR$DIVIDE 
Divide Two Decimal Strings 


The Divide Two Decimal Strings routine divides two decimal strings. 


Format 

STR$DIVIDE asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,total-digits 

,found-truncate-indicator ,csign ,cexp ,cdigits 

Returns 

OpenVMS usage: cond_value 

type longword (unsigned) 

access: write only 

mechanism: by value 
Arguments 

asign 

OpenVMS usage: longword_unsigned 

type longword (unsigned) 

access: read only 

mechanism: by reference 


Sign of the first operand. The asign argument is the address of an unsigned 
longword containing the sign of the first operand. A value of 0 is considered 
positive; a value of 1 is considered negative. 


aexp 
OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which adigjits is multiplied to get the absolute value of the first 
operand. The aexp argument is the address of the first operand’s exponent. 


adigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


First operand’s numeric text string. The adigits argument is the address of a 
descriptor pointing to the first operand’s numeric string. The string must be an 
unsigned decimal number. 


bsign 

OpenVMS usage: longword_unsigned 
type longword (unsigned) 
access: read only 
mechanism: by reference 
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STR-32 


Sign of the second operand. The bsign argument is the address of an unsigned 
longword containing the second operand’s string. A value of 0 is considered 
positive; a value of 1 is considered negative. 


bexp 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which bdigits is multiplied to get the absolute value of the second 
operand. The bexp argument is the address of the second operand’s exponent. 


bdigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Second operand’s numeric text string. The bdigits argument is the address of a 
descriptor pointing to the second operand’s number string. The string must be an 
unsigned decimal number. 


total-digits 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Number of digits to the right of the decimal point. The total-digits argument 
is the address of a signed longword containing the number of total digits. 
STR$DIVIDE uses this number to carry out the division. 


round-truncate-indicator 
OpenVMS usage: mask_longword 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Indicator of whether STR$DIVIDE is to round or truncate the result; a value of 
O means truncate; a value of 1 means round. The round-truncate-indicator 
argument is the address of a longword bit mask containing this indicator. 


csign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Sign of the result. The csign argument is the address of an unsigned longword 
containing the sign of the result. A value of 0 is considered positive; a value of 1 
is considered negative. 
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STR$DIVIDE 
cexp 
OpenVMS usage: longword_signed 
type longword (signed) 
access: write only 
mechanism: by reference 


Power of 10 by which cdigjits is multiplied to get the absolute value of the result. 
The cexp argument is the address of a signed longword containing the exponent. 


cdigits 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Result’s numeric text string. The cdigits argument is the address of a descriptor 
pointing to the numeric string of the result. This string is an unsigned decimal 
number. 


Description 


STR$DIVIDE divides two decimal strings. The divisor and dividend are passed to 
STR$DIVIDE in three parts: (1) the sign of the decimal number, (2) the power 
of 10 needed to obtain the absolute value, and (3) the numeric string. The result 
of the division is also returned in those three parts. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

STR$ TRU String truncation warning. The destination 
string could not contain all of the characters in 
the result. 


Condition Values Signaled 


LIB$ INVARG Invalid argument. 
STR$_DIVBY_ZER Division by zero. 
STR$ FATINTERR Fatal internal error. An internal consistency 


check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$DIVIDE 
could not allocate heap storage for a dynamic 
or temporary string. 


STR$ WRONUMARG Wrong number of arguments. 
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STR$DIVIDE 
Example 
100 !+ 

! This BASIC example program uses STRSDIVIDE 

! to divide two decimal strings and truncates 
! the result. 

!- 

ASIGNS = 1% 

AEXP%S = 3% 

ADIGITSS = '1' 

BSIGNS = 0% 

BEXPS = -4% 

BDIGITSS = '2’ 

CSIGNS = 0% 

CEXP% = 0% 

CDIGITS$ = '0’ 

PRINT "A = "; ASIGN%S; AEXP%; ADIGITSS 

PRINT "B = "; BSIGN%; BEXP%; BDIGITSS 

CALL STRSDIVIDE (ASIGN%, AEXP%, ADIGITSS, & 

BSIGN%S, BEXP%, BDIGITSS, & 
3%, 0%, CSIGN%, CEXP%, CDIGITSS) 
PRINT "C = "; CSIGN%; CEXP%; CDIGITSS 
1500 END 


This BASIC program uses STR$DIVIDE to divide two decimal strings, A divided 
by B, where the following values apply: 


A =-1000 (ASIGN =1, AEXP =3, ADIGITS ='17) 
B =.0002 (BSIGN =0, BEXP =-4, BDIGITS ='27) 


The output generated by this program is as follows: 


A=1 31 
B=0 -4 2 
Cc = 1 -3 5000000000 


Thus, the decimal value of C equals -5000000 (CSIGN =1, CEXP =-3, CDIGITS 
= 5000000000). 
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STR$DUPL_CHAR 
Duplicate Character n Times 


Format 


The Duplicate Character n Times routine generates a string containing n 
duplicates of the input character. If the destination string is an “empty” dynamic 
length string descriptor, STR$DUPL_CHAR allocates and initializes the string. 


STR$DUPL_CHAR  destination-string [,repetition-count] [,ASClI-character] 


Corresponding JSB Entry Point 


Returns 


Arguments 


STR$SDUPL_CHAR_R8 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$DUPL_CHAR writes repetition-count 
copies of the input character. The destination-string argument is the address 
of a descriptor pointing to the destination string. The maximum length of the 
destination string for a 32-bit descriptor is 21©—1, or 65,535, bytes. 


On Alpha systems, the maximum length of the destination string for all 64-bit 
descriptor classes, except varying strings, is 24—1 bytes. The maximum length 
of a varying-length string is 2?©—1 for both 32-bit and 64-bit descriptors. 


repetition-count 
OpenVMS usage: longword_signed 


type longword (signed) 
access: read only 
mechanism: by reference 


Number of times ASCII-character is duplicated; this is an optional argument 
(if omitted, the default is 1). The repetition-count argument is the address of a 
signed longword containing the number. 


ASCll-character 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by reference 


STR-35 


STR$ Routines 
STR$DUPL_CHAR 


ASCII character that STR$DUPL_CHAR writes repetition-count times into the 
destination string. The ASCII-character argument is the address of a character 
string containing this character. This is an optional argument; if omitted, the 
default is a space. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

STR$ NEGSTRLEN Alternate success. The length argument 
contained a negative value; zero was used. 

STR$ TRU String truncation warning. The destination 


string could not contain all of the characters. 


Condition Values Signaled 


Example 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$DUPL_CHAR 
could not allocate heap storage for a dynamic or 
temporary string. 

STR$ STRTOOLON String length exceeds the maximum allowed for 
the destination-string descriptor. 


! This example uses STRSDUPL_CHAR to 


! duplicate the character 'A’ four times. 
_ 


EXTERNAL INTEGER FUNCTION STRSDUPL_CHAR 
STATUS% = STRSDUPL_CHAR (XS, 4%, 'A’ BY REF) 
PRINT X$ 

END 


These BASIC statements set X$ equal to "AAAA’. 
The output generated by this program is as follows: 
AAAA 
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STR$ELEMENT 
Extract Delimited Element Substring 


Format 


Returns 


Arguments 


The Extract Delimited Element Substring routine extracts an element from a 
string in which the elements are separated by a specified delimiter. 


STR$ELEMENT destination-string ,element-number ,delimiter-string ,source-string 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$ELEMENT copies the selected substring. 
The destination-string argument is the address of a descriptor pointing to the 
destination string. 


element-number 
OpenVMS usage: longword_signed 


type longword (signed) 
access: read only 
mechanism: by reference 


Element number of the delimited element substring to be returned. The 
element-number argument is the address of a signed longword containing 

the desired element number. Zero is used to represent the first delimited element 
substring, one is used to represent the second, and so forth. 


delimiter-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Delimiter string used to separate element substrings. The delimiter-string 
argument is the address of a descriptor pointing to the delimiter string. The 
delimiter-string argument must be exactly one character long. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 
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Description 


Source string from which STR$ELEMENT extracts the requested delimited 
substring. The source-string argument is the address of a descriptor pointing to 
the source string. 


STR$ELEMENT extracts an element from a string in which the elements are 
separated by a specified delimiter. 


For example, if source-string is MON “TUE*WED“THU*FRI“*SAT“SUN, 
delimiter-string is ~, and element-number is 2, then STR$ELEMENT returns 
the string WED. 


Once the specified element is located, all the characters in that delimited element 
are returned. That is, all characters between the element-number and the 
element-number + 1 delimiters are written to destination-string. At least 
element-number delimiters must be found. If exactly element-number 
delimiters are found, then all values from the element-number delimiter to the 
end of the string are returned. If element-number equals 0 and no delimiters 
are found, the entire input string is returned. 


STR$ELEMENT duplicates the functions of the DCL lexical function 
FSELEMENT. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

STR$ INVDELIM Delimiter string is not exactly one character long 
(warning). 

STR$ NOELEM Not enough delimited characters found to satisfy 
requested element number (warning). 

STR$ TRU String truncation. The destination string could 


not contain all the characters in the delimited 
substring (warning). 


Condition Values Signaled 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ INSVIRMEM Insufficient virtual memory. STR$ELEMENT 
could not allocate heap storage for a dynamic or 
temporary string. 
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STR$FIND_FIRST_IN_ SET 
Find First Character in a Set of Characters 


Format 


Returns 


Arguments 


Description 


The Find First Character in a Set of Characters routine searches a string, 
comparing each character to the characters in a specified set of characters. The 
string is searched character by character, from left to right. STR$FIND_FIRST_ 
IN_SET returns the position of the first character in the string that matches any 
of the characters in the selected set of characters. 


STR$FIND_FIRST_IN_SET  source-string ,set-of-characters 


OpenVMS usage: longword_signed 


type longword (signed) 
access: write only 
mechanism: by value 


Position in source-string where the first match is found; zero if no match is 
found. 


On Alpha systems, if the relative position of the substring can exceed 232—1, 
assign the return value to a quadword to ensure that you retrieve the correct 
relative position. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


String that STR$FIND_FIRST_IN_SET compares to the set of characters, looking 
for the first match. The source-string argument is the address of a descriptor 
pointing to the character string. 


set-of-characters 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Set of characters that STR$FIND_FIRST_IN_ SET is searching for in the string. 
The source-string argument is the address of a descriptor pointing to the set of 
characters. 


STR$FIND_FIRST_IN SET compares each character in the string to every 
character in the specified set of characters. As soon as the first match is found, 
STR$FIND_FIRST_IN_ SET returns the position in the string where the matching 
character was found. If no match is found, 0 is returned. If either source-string 
or set-of-characters is of zero length, 0 is returned. 
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Condition Value Signaled 


Example 
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STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


PROGRAM FIND_FIRST (INPUT, OUTPUT) ; 


+} 
This example uses STRSFIND_FIRST_IN_SET 
to find the first character in the source 
string (STRING1) that matches a character 
in the set of characters being searched for 
(CHARS) . 


First, declare the external function. 
=} 
FUNCTION STRSFIND_FIRST_IN_SET(STRING : 
VARYING [A] OF CHAR; SETOFCHARS : 
VARYING [B] OF CHAR) : INTEGER; 
EXTERN; 


"| 


{ Declare the variables used in the main program. 


VAR 
STRING1 : VARYING [256] OF CHAR; 
CHARS : VARYING [256] OF CHAR; 
RET_STATUS : INTEGER; 
+} 


Begin the main program. Read the source string 
and the set of characters being searched for. Call 
STRSFIND_FIRST_IN_SET to find the first match. 
Print the result. 


BEGIN 
WRITELN(’ENTER THE STRING: '); 
READLN (STRING1) ; 
WRITELN(’ENTER THE SET OF CHARACTERS: '); 
READLN (CHARS) ; 
RET_STATUS := STRSFIND_FIRST_IN_SET(STRING1, CHARS) ; 
WRITELN (RET_STATUS) ; 

END. 


This Pascal program demonstrates the use of STR$FIND_FIRST_IN_SET. If you 
run this program and set STRING1 equal to ABCDEFGHIJ K and CHARS equal 
to XYZA, the value of RET_STATUS is 1. The output generated by this program 
is as follows: 


ENTER THE STRING: 
ABCDEFGHIJK 
ENTER THE SET OF CHARACTERS: 
XYZA 

1 
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STR$FIND_FIRST_NOT_IN_ SET 
Find First Character That Does Not Occur in Set 


Format 


Returns 


Arguments 


The Find First Character That Does Not Occur in Set routine searches a string, 
comparing each character to the characters in a specified set of characters. The 
string is searched character by character, from left to right. STR$FIND_FIRST_ 
NOT_IN_SET returns the position of the first character in the string that does 
not match any of the characters in the selected set of characters. 


STR$FIND_FIRST_NOT_IN_SET _ source-string ,set-of-characters 


OpenVMS usage: longword_signed 


type longword (signed) 
access: write only 
mechanism: by value 


Position in source-string where a nonmatch was found. 


On Alpha systems, if the relative position of the substring can exceed 232—1, 
assign the return value to a quadword to ensure that you retrieve the correct 
relative position. 


Returned Value Condition 


0 Either all characters in source-string match some 
characters in set-of-characters, or there were no 
characters in set-of-characters. 

1 Either the first nonmatching character in source-string 
was found in position 1, or there were no characters in 
source-string. 

N The first nonmatching character was found in position N 
within source-string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


String that STR$FIND_ FIRST NOT_IN_SET searches. The source-string 
argument is the address of a descriptor pointing to the string. 


set-of-characters 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 
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Description 


The set of characters that STR$FIND_ FIRST NOT_IN_ SET compares to the 
string, looking for a nonmatch. The set-of-characters argument is the address 
of a descriptor pointing to this set of characters. 


STR$FIND_FIRST_NOT_IN_SET searches a string, comparing each character to 
the characters in a specified set of characters. The string is searched character 
by character, from left to right. When STR$FIND_FIRST_NOT_IN_SET finds a 
character from the string that is not in set-of-characters, it stops searching and 
returns, as the value of STR$FIND_FIRST_NOT_IN_SET, the position in source- 
string where it found the nonmatching character. If all characters in the string 
match some character in the set of characters, STR$FIND_FIRST_NOT_IN_SET 
returns 0. If the string is of zero length, the position returned is 1 since none of 
the elements in the set of characters (particularly the first element) can be found 
in the string. If there are no characters in the set of characters, 0 is returned 
since “nothing” can always be found. 


Condition Value Signaled 


Example 


STR-42 


STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


PROGRAM NOT_IN_SET (INPUT, OUTPUT) ; 


+} 
This example uses STRSFIND_FIRST_NOT_IN_SET 
to find the position of the first nonmatching 
character from a set of characters (CHARS) 
in a source string (STRING1). 


First, declare the external function. 
=} 
FUNCTION STRSFIND_FIRST_NOT_IN_SET(STRING : 
VARYING [A] OF CHAR; SETOFCHARS : 


VARYING [B] OF CHAR) : INTEGER; 
EXTERN; 


{+} 
{ Declare the variables used in the main program. 
{-} 


VAR 
STRING1 : VARYING [256] OF CHAR; 
CHARS : VARYING [256] OF CHAR; 
RET_STATUS : INTEGER; 


{ 
{ Begin the main program. Read the source string 

{ and set of characters. Call STRSFIND_FIRST_NOT_IN_SET. 
{ Print the result. 

{ 


STR$ Routines 
STR$FIND_FIRST_NOT_IN SET 


BEGIN 
WRITELN(’ENTER THE STRING: '); 
READLN (STRING1) ; 
WRITELN(’ENTER THE SET OF CHARACTERS: '); 
READLN (CHARS) ; 
RET_STATUS := STRSFIND_FIRST_NOT_IN_SET(STRING1, CHARS) ; 
WRITELN (RET_STATUS) ; 
END. 


This Pascal program demonstrates the use of STR$FIND_ FIRST _NOT_IN_ SET. 
If you run this program and set STRING1 equal to FORTUNATE and CHARS 
equal to FORT, the value of RET_STATUS is 5. 


The output generated by this program is as follows: 


ENTER THE STRING: 

FORTUNATE 

ENTER THE SET OF CHARACTERS: 
FORT 


5 
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STR$FIND_FIRST_SUBSTRING 
Find First Substring in Input String 


The Find First Substring in Input String routine finds the first substring (in a 
provided list of substrings) occurring in a given string. 


Format 
STR$FIND_FIRST_SUBSTRING _ source-string ,index ,substring-index ,substring 
[,substring...] 
Returns 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The values returned by STR$FIND_FIRST_SUBSTRING and the conditions to 
which they translate are as follows: 
Returned Value Condition 
0 source-string did not contain any of the specified 
substrings. 
1 STR$FIND_FIRST_ SUBSTRING found at least one of 
the specified substrings in source-string. 
Arguments 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


String that STR$FIND_ FIRST SUBSTRING searches. The source-string 
argument is the address of a descriptor pointing to the string. 


index 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 


Earliest position within source-string at which STR$FIND_FIRST_ SUBSTRING 
found a matching substring; zero if no matching substring was found. The index 
argument is the address of a signed longword containing this position. 


substring-index 
OpenVMS usage: longword_signed 


type: longword (signed) 
access: write only 
mechanism: by reference 
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Ordinal number of the substring that matched (1 for the first, 2 for the second, 
and so on), or zero if STR$FIND_FIRST SUBSTRING found no substrings that 
matched. The substring-index argument is the address of a signed longword 
containing this ordinal number. 


substring 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Specified substring for which STR$FIND_FIRST_SUBSTRING searches in 
source-string. The substring argument is the address of a descriptor pointing 
to the first substring. You can specify multiple substrings to search for. 


substring 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Additional specified substring for which STR$FIND_FIRST SUBSTRING 
searches in source-string. The substring argument is the address of a 
descriptor pointing to the substring. You can specify multiple substrings to 
search for. 


Description 


STR$FIND_FIRST_ SUBSTRING takes as input a string to be searched and an 
unspecified number of substrings for which to search. It searches the specified 
string and returns the position of the substring that is found earliest in the 
string. This is not necessarily the position of the first substring specified. That 
is, STR$FIND_FIRST SUBSTRING returns the position of the leftmost matching 
substring. The order in which the substrings are searched for is irrelevant. 


Unlike many of the compare and search routines, STR$FIND_FIRST_ 
SUBSTRING does not return the position in a return value. The position of 
the substring which is found earliest in the string is returned in the index 
argument. If none of the specified substrings is found in the string, the value of 
index is 0. 


Zero-length strings, or null arguments, produce unexpected results. Any time 
the routine is called with a null substring as an argument, STR$FIND_FIRST_ 
SUBSTRING always returns the position of the null substring as the first 
substring found. All other substrings are interpreted as appearing in the string 
after the null string. 


Condition Values Signaled 


STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ WRONUMARG Wrong number of arguments. You must supply 
at least one substring. 
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Example 
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! This is a BASIC program demonstrating the use of 

! STRSFIND_FIRST_SUBSTRING. This program takes as input 
! four strings that are listed in a data statement 

! at the end of the program. STRSFIND_FIRST_SUBSTRING 

! is called four times (once for each string) 

! to find the first substring occurring in the given 

! string. 


OPTION TYPE = EXPLICIT 


DECLARE STRING MATCH_STRING 
DECLARE LONG RET_STATUS, & 
INDEX, & 
I, & 


SUB_STRING_NUM 
EXTERNAL LONG FUNCTION STRSFIND_FIRST_SUBSTRING 


FOR I = 1 TO 4 
READ MATCH_STRING 
RET_STATUS = STRSFIND_FIRST_SUBSTRING( MATCH_STRING, & 
INDEX, SUB_STRING_NUM, ‘ING’, ‘CK’, 'TH’) 
IF RET_STATUS = 0% THE 
PRINT MATCH_STRING;" did not contain any of the substrings" 


ELSE 
SELECT SUB_STRING_NUM 
CASE 1 
PRINT MATCH_STRING;" contains ING at position"; INDEX 
CASE 2 
PRINT MATCH_STRING;" contains CK at position"; INDEX 
CASE 3 
PRINT MATCH_STRING;" contains TH at position"; INDEX 
END SELECT 
END IF 
NEXT I 


2 DATA CHUCKLE, RAINING, FOURTH, THICK 
3 END 


This BASIC program demonstrates the use of STR$FIND_FIRST_SUBSTRING. 
The output generated by this program is as follows: 


$ BASIC FINDSUB 

$ LINK FINDSUB 

S$ RUN FINDSUB 

CHUCKLE contains CK at position 4 
RAINING contains ING at position 5 
FOURTH contains TH at position 5 
THICK contains TH at position 1 


Note that “THICK” contains both the substrings “TH” and “CK”. STR$FIND_ 
FIRST SUBSTRING locates the “CK” substring in “THICK”, and then locates 
the “TH” substring. However, since the “TH” substring is the earliest, or leftmost 
matching substring, its ordinal number is returned in substring-index, and the 
point at which “TH” occurs is returned in index. 
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STR$FREE1_DX 
Free One Dynamic String 


The Free One Dynamic String routine deallocates one dynamic string. 


Format 
STR$FREE1_DX _ string-descriptor 


Corresponding JSB Entry Point 
STR$FREE1_DX_R4 


Returns 


OpenVMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Argument 


string-descriptor 

OpenVMS usage: char_string 
type: character string 
access: modify 
mechanism: by descriptor 


Dynamic string descriptor of the dynamic string that STR$FREE1 DX 


deallocates. The string-descriptor argument is the address of a descriptor 
pointing to the string to be deallocated. The descriptor’s CLASS field is checked. 


Description 


STR$FREE1 DX deallocates the described string space and flags the descriptor 
as describing no string at all. The descriptor’s POINTER and LENGTH fields 
contain 0. 


Condition Values Returned 
SS$ NORMAL Normal successful completion. 
Condition Values Signaled 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 


STR$ERRFREDYN Error freeing dynamic string descriptor. 
LIB$FREE_VM OR LIB$FREE_VM_64 failed 
to free the descriptor. 
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STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
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STR$ Routines 
STR$GET1_DX 


STR$GET1_DX 
Allocate One Dynamic String 


Format 


The Allocate One Dynamic String routine allocates a specified number of bytes of 
virtual memory to a specified dynamic string descriptor. 


STR$GET1_DX_ word-integer-length ,character-string 


Corresponding JSB Entry Point 


Returns 


Arguments 


Description 


STR$GET1_DX_R4 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


word-integer-length 
OpenVMS usage: word_unsigned 


type word (unsigned) 
access: read only 
mechanism: by reference 


Number of bytes that STR$GET1 DX allocates. The word-integer-length 
argument is the address of an unsigned word containing this number. 


character-string 
OpenVMS usage: char_string 


type: character string 
access: modify 
mechanism: by descriptor 


Dynamic string descriptor to which STR$GET1 DX allocates the area. The 
character-string argument is the address of the descriptor. The descriptor’s 
CLASS field is checked. 


STR$GET1 DX allocates a specified number of bytes of dynamic virtual memory 
to a specified string descriptor. The descriptor must be dynamic. 


If the string descriptor already has dynamic memory allocated to it, but the 
amount allocated is less than word-integer-length, STR$GET1_ DX deallocates 
that space before it allocates new space. 
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Note 


Compaq recommends use of the STR$GET1_DX or STR$GET1_DX_64 
(Alpha only) routine for allocating a string to a dynamiclength string 
descriptor. Simply filling in the length and pointer fields of a dynamic- 
length string descriptor can cause serious and unexpected problems with 
string management. 


Use STR$FREE1 DX to deallocate a string allocated by STR$GET1 DX. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


Condition Values Signaled 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$GET1_DX 
could not allocate heap storage for a dynamic or 
temporary string. 


STR$ Routines 
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STR$GET1_DX_64 (Alpha Only) 
Allocate One Dynamic String 


Format 


The Allocate One Dynamic String routine allocates a specified number of bytes of 
virtual memory to a specified dynamic string descriptor. 


STR$GET1_DX_64 quad-integer-length ,character-string 


Corresponding JSB Entry Point 


Returns 


Arguments 


Description 


STR$GET1_DX_R4 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


quad-integer-length 
OpenVMS usage: quadword_unsigned 


type quadword (unsigned) 
access: read only 
mechanism: by reference 


Number of bytes that STR$GET1_DX_64 allocates. The quad-integer-length 
argument is the address of an unsigned quadword containing this number. 


character-string 
OpenVMS usage: char_string 


type: character string 
access: modify 
mechanism: by descriptor 


Dynamic string descriptor to which STR$GET1_DX_64 allocates the area. The 
character-string argument is the address of the descriptor. The descriptor’s 
CLASS field is checked. 


STR$GET1_DX_64 allocates a specified number of bytes of dynamic virtual 
memory to a specified 64-bit string descriptor. The descriptor must be dynamic. 


If the string descriptor already has dynamic memory allocated to it, but 
the amount allocated is less than quad-integer-length, STR$GET1 DX_64 
deallocates that space before it allocates new space. 
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Note 


Compaq recommends use of the STR$GET1_DX or STR$GET1_DX_64 
(Alpha only) routine for allocating a string to a dynamiclength string 
descriptor. Simply filling in the length and pointer fields of a dynamic- 
length string descriptor can cause serious and unexpected problems with 
string management. 


Use STR$FREE1 DX to deallocate a string allocated by STR$GET1_DX_64. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


Condition Values Signaled 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$_INSVIRMEM Insufficient virtual memory. STR$GET1_DX_64 
could not allocate heap storage for a dynamic or 
temporary string. 
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STR$LEFT 


Extract a Substring of a String 


Format 


The Extract a Substring of a String routine copies a substring beginning at the 
first character of a source string into a destination string. 


STR$LEFT destination-string ,source-string ,end-position 


Corresponding JSB Entry Point 


Returns 


Arguments 


STR$LEFT_R8 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$LEFT copies the substring. The destination- 
string argument is the address of a descriptor pointing to the destination 
string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string from which STR$LEFT extracts the substring that it copies into the 
destination string. The source-string argument is the address of a descriptor 
pointing to the source string. 


end-position 

OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 


Relative position in the source string at which the substring ends. The end- 
position argument is the address of a signed longword containing the ending 
position. 


STR$LEFT copies all characters in the source string from position 1 (the leftmost 
position) to the position number specified in this end-position argument. 
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STRS$LEFT 


Description 


STR$LEFT extracts a substring from a source string and copies that substring 
into a destination string. STR$LEFT defines the substring by specifying the 
relative ending position in the source string. The relative starting position in 
the source string is 1. The source string is unchanged, unless it is also the 
destination string. 


This is a variation of STR$POS _EXTR. Other routines that may be used to 
extract and copy a substring are STR$RIGHT and STR$LEN_EXTR. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

STR$_ILLSTRPOS Alternate success. An argument referenced a 
character position outside the specified string. A 
default value was used. 

STR$ ILLSTRSPE Alternate success. The length of the substring 
was too long for the specified destination string. 
Default values were used. 

STR$ TRU String truncation warning. The destination 
string could not contain all the characters copied 
from the source string. 


Condition Values Signaled 


Example 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 


STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ INSVIRMEM Insufficient virtual memory. STR$LEFT could 
not allocate heap storage for a dynamic or 
temporary string. 


PROGRAM LEFT (INPUT, OUTPUT) ; 


+ 
This Pascal program demonstrates the use of 
STRSLEFT. This program reads in a source string 
and the ending position of a substring. 

t returns a substring consisting of all 
characters from the beginning (left) of the 
source string to the ending position entered. 


+ 
Declare the external procedure, STRSLEFT. 
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PROCEDURE STRSLEFT(%DESCR DSTSTR: VARYING 
[A] OF CHAR; SRCSTR 
VARYING [B] OF CHAR; ENDPOS : 
INTEGER); EXTERN; 


{+} 
{ Declare the variables used by this program. 
{-} 
VAR 
SRC_STR : VARYING [256] OF CHAR; 
DST_STR : VARYING [256] OF CHAR; 
END_POS : INTEGER; 


{+} 

{ Begin the main program. Read the source string 
{ and ending position. Call STRSLEFT. Print the 
{ results. 

{-} 


WRITELN(’ENTER THE SOURCE STRING: '); 
READLN (SRC_STR) ; 

TELN (‘ENTER THE ENDING POSITION’ ); 
VRITELN(’OF THE SUBSTRING: '); 

READLN (END_POS) ; 

STRSLEFT(DST_STR, SRC_STR, END_POS); 
VRITELN; 

RITELN(’THE SUBSTRING IS: ',DST_STR); 


This Pascal example shows the use of STR$LEFT. One sample of the output of 
this program is as follows: 


$ PASCAL LEFT 

$ LINK LEFT 

$ RUN LEFT 

ENTER THE SOURCE STRING: MAGIC CARPET 
ENTER THE ENDING POSITION OF 

THE SUBSTRING: 9 


THE SUBSTRING IS: MAGIC CAR 
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STR$LEN_EXTR 
Extract a Substring of a String 


Format 


The Extract a Substring of a String routine copies a substring of a source string 
into a destination string. 


STR$LEN_EXTR_ destination-string ,source-string ,start-position 
,longword-integer-length 


Corresponding JSB Eniry Point 


Returns 


Arguments 
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STR$LEN_EXTR_R8 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$LEN_EXTR copies the substring. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string from which STR$LEN_EXTR extracts the substring that it copies 
into the destination string. The source-string argument is the address of a 
descriptor pointing to the source string. 


start-position 
OpenVMS usage: longword_signed 


type: longword (signed) 
access: read only 
mechanism: by reference 


Relative position in the source string at which STR$LEN_EXTR begins copying 
the substring. The start-position argument is the address of a signed longword 
containing the starting position. 


STR$ Routines 
STR$LEN_EXTR 


longword-integer-length 
OpenVMS usage: longword_signed 


type: longword (signed) 
access: read only 
mechanism: by reference 


Number of characters in the substring that STR$LEN_EXTR copies to the 
destination string. The longword-integer-length argument is the address of a 
signed longword containing the length of the substring. 


Description 


STR$LEN_EXTR extracts a substring from a source string and copies that 
substring into a destination string. 


STR$LEN_EXTR defines the substring by specifying the relative starting position 
in the source string and the number of characters to be copied. The source string 
is unchanged, unless it is also the destination string. 


If the starting position is less than 1, 1 is used. If the starting position is greater 
than the length of the source string, the null string is returned. If the length is 
less than 1, the null string is also returned. 


Other substring routines are STR$RIGHT, STR$LEFT, and STR$POS_EXTR. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


STR$ ILLSTRPOS STR$LEN_EXTR completed successfully, but an 
argument referenced a character position outside 
the specified string. A default value was used. 


STR$ ILLSTRSPE STR$LEN_EXTR completed successfully, except 
that the length was too long for the specified 
string. Default values were used. 


STR$ NEGSTRLEN STR$LEN_EXTR completed successfully, except 
that longword-integer-length contained a 
negative value. Zero was used. 


STR$ TRU String truncation warning. The destination 
string could not contain all the characters copied 
from the source string. 


Condition Values Signaled 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 


STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR-57 
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Example 
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STR$ INSVIRMEM Insufficient virtual memory. STR$LEN_EXTR 


10 
800 


900 


100 


901 


200 


could not allocate heap storage for a dynamic or 
temporary string. 


CHARACTER* 131 IN_STRING 

CHARACTER* 1 FRONT_CHAR 

CHARACTER* 1 TAIL _ CHAR 

INTEGER STRSLEN_EXTR, STRSREPLACE, STRSTRIM 

INTEGER FRONT_POSITION, TAIL POSITION 

WRITE (6, 800) 

FORMAT (’ Enter a string, 131 characters or less:’,$) 
READ (5, 900, END=200) IN_STRING 

FORMAT (A) 
STATUS = STRSTRIM (IN_STRING, IN_STRING, LENGTH) 


DO 100 I = 1, LENGTH/2 
FRONT_POSITION = I 


AIL_POSITION = LENGTH + 1 - I 
ISTATUS = STRSLEN_EXTR ( FRONT_CHAR, IN_STRING, FRONT_POSITION, 
REF (1) ) 


ISTATUS = STRSLEN_EXTR ( TAIL_CHAR, IN_STRING, TAIL_POSITION, 
REF (1) ) 


STATUS = STRSREPLACE ( IN_STRING, IN_STRING, FRONT_POSITION, 
FRONT_POSITION, TAIL_CHAR) 


ISTATUS = STRSREPLACE ( IN_STRING, IN_STRING, TAIL_POSITION, 
TAIL_POSITION, FRONT_CHAR) 


CONTINUE 

WRITE (6, 901) IN_STRING 

FORMAT (’ Reversed string is : ',/,1X,A) 
GOTO 10 

CONTINUE 

END 


This Fortran program accepts a string as input and writes the string in reverse 
order as output. This program continues to prompt for input until Ctrl/Z is 
pressed. One sample of the output generated by this program is as follows: 


$ FORTRAN REVERSE 

$ LINK REVERSE 

S$ RUN REVERSE 

Enter a string, 131 characters or less: Elephants often have 
flat feet. 


Reversed string is : 
.teef talf evah netfo stnahpelE 


Enter a string, 131 characters or less: CTRL/Z 


$ 
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STR$MATCH_WILD 
Match Wildcard Specification 


Format 


Returns 


Arguments 


Description 


The Match Wildcard Specification routine compares a pattern string that includes 
wildcard characters with a candidate string. 


STR$MATCH_WILD  candidate-string ,pattern-string 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


Returns a condition value of STR$ MATCH if the strings match and STR$_ 
NOMATCH if they do not match. 


candidate-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


String that is compared to the pattern string. The candidate-string argument 
is the address of a descriptor pointing to the candidate string. 


pattern-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


String containing wildcard characters. The pattern-string argument is the 
address of a descriptor pointing to the pattern string. The wildcards in the 
pattern string are translated when STR$MATCH_WILD searches the candidate 
string to determine if it matches the pattern string. 


STR$MATCH_WILD translates wildcard characters and searches the candidate 
string to determine if it matches the pattern string. The pattern string may 
contain either one or both of the two wildcard characters, asterisk (*) and 
percent (%). The asterisk character is mapped to zero or more characters. The 
percent character is mapped to only one character. 


The two wildcard characters that may be used in the pattern string may be 
used only as wildcards. If the candidate string contains an asterisk or percent 
character, the condition STR$ MATCH is returned. Wildcard characters are 
translated literally. There is no restriction on whether either wildcard character 
in the pattern string can match a percent or asterisk that is translated literally 
in the candidate string. 
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Condition Values Returned 


STR$ MATCH The candidate string and the pattern string 
match. 

STR$ NOMATCH The candidate string and the pattern string do 
not match. 


Condition Value Signaled 


STR$ ILLSTRCLA Illegal string class. Severe error. The descriptor 
of candidate-string and/or pattern-string 
contains a class code that is not supported by the 
OpenVMS calling standard. 


Example 


Example program using STRSMATCH_WILD. 


The following program reads in a master pattern string and then 
compares that to input strings until it reaches the end of the 
input file. For each string comparison done, it prints 

either ‘Matches pattern string’ or ’Doesn’t match pattern string’. 


/ 


declare str$match_wild 
external entry (character(*) varying, character(*) varying) 
returns (bit(1)); 


Ca, a a er, 


example: procedure options (main); 


dcl pattern_string character(80) varying; 
dcl test_string character (80) varying; 


on endfile(sysin) stop; 
put skip; 
get list (pattern_string) options (prompt (’Pattern string> ’)); 


do while( '1’b ); 
get skip list (test_string) options(prompt(’Test string> ’)); 
if str$match_wild(test_string, pattern_string) 
then put skip list (’Matches pattern string’); 
else put skip list(’Doesn’’t match pattern string’); 
end; 


end; 
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This PL/I program demonstrates the use of STR$MATCH_ WILD. The output 
generated by this program is as follows: 


$ PLI MATCH 

$ LINK MATCH 

S$ RUN MATCH 

Pattern string> ‘Must match me exactly.’ 
Test string> ‘Will this work? Must match me exactly.’ 
Doesn’t match pattern string 

Test string> ’must match me exactly’ 
Doesn’t match pattern string 

Test string> ‘must match me exactly.’ 
Doesn’t match pattern string 

Test string> ‘’Must match me exactly’ 
Doesn’t match pattern string 

Test String> ‘Must match me exactly.’ 
atches pattern string 
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STR$MUL 


STR$MUL 


Multiply Two Decimal Strings 


Format 


Returns 


Arguments 
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The Multiply Two Decimal Strings routine multiplies two decimal strings. 


STR$MUL asign ,aexp ,adigits ,osign ,bexp ,bdigits ,csign ,cexp ,cdigits 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 

asign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Sign of the first operand. The asign argument is the address of an unsigned 
longword containing the first operand'’s sign. A value of 0 is considered positive a 
value of 1 is considered negative. 


aexp 
OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which adigjts is multiplied to get the absolute value of the first 
operand. The aexp argument is the address of a signed longword containing this 
exponent. 


adigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


First operand’s numeric text string. The adigits argument is the address of a 
descriptor pointing to the numeric string of the first operand. The string must be 
an unsigned decimal number. 


bsign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
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Sign of the second operand. The bsign argument is the address of an unsigned 
longword containing the sign of the second operand. A value of 0 is considered 
positive; a value of 1 is considered negative. 


bexp 

OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which bdigits is multiplied to get the absolute value of the second 
operand. The bexp argument is the address of a signed longword containing this 
exponent. 


bdigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Second operand’s numeric text string. The bdigits argument is the address of a 
descriptor pointing to the second operand’s numeric string. The string must be an 
unsigned decimal number. 


csign 

OpenVMS usage: longword_unsigned 
type longword (unsigned) 
access: write only 
mechanism: by reference 


Sign of the result. The csign argument is the address of an unsigned longword 
containing the sign of the result. A value of 0 is considered positive; a value of 1 
is considered negative. 


cexp 
OpenVMS usage: longword_signed 
type longword (signed) 
access: write only 
mechanism: by reference 


Power of 10 by which cdigjits is multiplied to get the absolute value of the result. 
The cexp argument is the address of a signed longword containing this exponent. 


cdigits 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Result’s numeric text string. The cdigits argument is the address of a descriptor 
pointing to the numeric string of the result. The string is an unsigned decimal 
number. 
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Description 


STR$MUL multiplies two decimal strings. The numbers to be multiplied are 
passed to STR$MUL in three parts: (1) the sign of the decimal number, (2) the 
power of 10 needed to obtain the absolute value, and (3) the numeric string. The 
result of the multiplication is also returned in those three parts. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

STR$ TRU String truncation warning. The destination 
string could not contain all the characters in the 
result. 


Condition Values Signaled 


LIB$ INVARG Invalid argument. 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ INSVIRMEM Insufficient virtual memory. STR$MUL could not 
allocate heap storage for a dynamic or temporary 
string. 

STR$ WRONUMARG Wrong number of arguments. 

Example 
100 !+ 


! This example program uses 

STRSMUL to multiply two decimal 
strings (A and B) and place the 
results in a third decimal string, 


(C) 

ASIGNs = 1% 

AEXP% = 3% 

ADIGITSS = ‘1’ 

BSIGN% = 0% 

BEXP% = -4% 

BDIGITSS = '2' 

CSIGNS = 0% 

CEXP% = 0% 

CDIGITS$ = '0' 

PRINT "A = "; ASIGNS; AEXP%S; ADIGITSS 

PRINT "B = "; BSIGN%S; BEXP%; BDIGITSS 

CALL STRSMUL (ASIGNS, AEXP%, ADIGITSS, & 
BSIGN%, BEXP%, BDIGITSS, & 
CSIGN%, CEXP%, CDIGITSS) 

PRINT "C = "; CSIGN%S; CEXP%; CDIGITSS 


999 END 
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This BASIC example uses STR$MUL to multiply two decimal strings, where the 
following values apply: 


A =-1000 (ASIGN =1, AEXP =3, ADIGITS ='1") 
B =.0002 (BSIGN =0, BEXP =-4, BDIGITS =727) 


The output generated by this program is as follows; note that the decimal value 
C equals -.2 (CSIGN =1, CEXP =-1, CDIGITS =2). 


1 e371 
0-4 2 
LS, 2 


A 
B 
C 
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STR$POSITION 
Return Relative Position of Substring 


Format 


The Return Relative Position of Substring routine searches for the first occurrence 
of a single substring within a source string. If STR$POSITION finds the 
substring, it returns the relative position of that substring. If the substring 

is not found, STR$POSITION returns a zero. 


STR$POSITION  source-string ,substring [,start-position] 


Corresponding JSB Eniry Point 


Returns 


Arguments 
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STRSPOSITION_R6 


OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Relative position of the first character of the substring. Zero is the value returned 
if STR$POSITION did not find the substring. 


On Alpha systems, if the relative position of the substring can exceed 232—1, 
assign the return value to a quadword to ensure that you retrieve the correct 
relative position. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string within which STR$POSITION searches for the substring. The 
source-string argument is the address of a descriptor pointing to the source 
string. 


substring 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Substring for which STR$POSITION searches. The substring argument is the 
address of a descriptor pointing to the substring. 


start-position 
OpenVMS usage: longword_signed 


type: longword (signed) 
access: read only 
mechanism: by reference 


Description 


STR$ Routines 
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Relative position in the source string at which STR$POSITION begins the search. 
The start-position argument is the address of a signed longword containing the 
starting position. Although this is an optional argument, it is required if you are 
using the) SB entry point. 


If start-position is not supplied, STR$POSITION starts the search at the first 
character position of source-string. 


STR$POSITION returns the relative position of the first occurrence of a substring 
in the source string. The value returned is an unsigned longword. The relative 
character positions are numbered 1, 2, 3, and so on. A value of 0 indicates that 
the substring was not found. 


If the substring has a zero length, the minimum value of start-position (and the 
length of source-string plus one) is returned by STR$POSITION. 


If the source string has a zero length and the substring has a nonzero length, 
zero is returned, indicating that the substring was not found. 


Condition Values Signaled 


Example 


STR$ ILLSTRCLA Illegal string class. The class code found in the 
string class field of a descriptor is not a string 
class code allowed by the OpenVMS calling 
standard. 


PROGRAM POSITION (INPUT, OUTPUT) ; 


+} 
This example uses STRSPOSITION to determine 
the position of the first occurrence of 
a substring (SUBSTRING) within a source 
string (STRING1) after the starting 
position (START). 


First, declare the external function. 
= 
FUNCTION STRSPOSITION(SRCSTR : VARYING [A] 


OF CHAR; SUBSTR : VARYING [B] OF CHAR; 
STARTPOS : INTEGER) : INTEGER; EXTERN; 


{ Declare the variables used in the main program. 


VAR 
STRING1 : VARYING [256] OF CHAR; 
SUBSTRING : VARYING [256] OF CHAR; 
START : INTEGER; 
RET_STATUS : INTEGER; 
+} 


{ 

{ Begin the main program. Read the string and substring. 

{ Set START equal to 1 to begin looking for the substring 

{ at the beginning of the source string. Call STRSPOSITION 
{ and print the result. 

{ 
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BEGIN 

RITELN(’ENTER THE STRING: '); 

READLN (STRING1) ; 

RITELN(’ ENTER THE SUBSTRING: '); 

READLN (SUBSTRING) ; 

START := 1; 

RET_STATUS := STRSPOSITION(STRING1, SUBSTRING, START); 
RITELN (RET_STATUS) ; 

END. 


This Pascal program demonstrates the use of STR$POSITION. If you run this 
program and set STRING1 equal to KITTEN and substring equal to TEN, the 
value of RET_STATUS is 4. 


The output generated by this program is as follows: 


ENTER THE STRING: 
KITTEN 
ENTER THE SUBSTRING: 
TEN 

4 
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STR$POS_EXTR 
Extract a Substring of a String 


Format 


The Extract a Substring of a String routine copies a substring of a source string 
into a destination string. 


STR$POS_EXTR_ destination-string ,source-string ,start-position ,end-position 


Corresponding JSB Entry Point 


Returns 


Arguments 


STR$POS_EXTR_R8 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$POS EXTR copies the substring. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string from which STR$POS _EXTR extracts the substring that it copies 
into the destination string. The source-string argument is the address of a 
descriptor pointing to the source string. 


start-position 
OpenVMS usage: longword_signed 


type: longword (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 


Relative position in the source string at which STR$POS_EXTR begins copying 
the substring. The start-position argument is the address of a signed longword 
containing the starting position. 
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Description 


end-position 

OpenVMS usage: longword_signed 

type: longword (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for J SB entry 


point 


Relative position in the source string at which STR$POS EXTR stops copying 
the substring. The end-position argument is the address of a signed longword 
containing the ending position. 


STR$POS _EXTR extracts a substring from a source string and copies the 
substring into a destination string. STR$POS EXTR defines the substring by 
specifying the relative starting and ending positions in the source string. The 
source string is unchanged, unless it is also the destination string. 


If the starting position is less than 1, 1 is used. If the starting position is greater 
than the length of the source string, the null string is returned. If the ending 
position is greater than the length of the source string, the length of the source 
string is used. 


Other routines that can be used to extract and copy a substring are STR$LEFT, 
STR$RIGHT, and STR$LEN_EXTR. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
STR$_ILLSTRPOS Alternate success. An argument referenced a 


character position outside the specified string. A 
default value was used. 


STR$_ILLSTRSPE Alternate success. End-position was less than 
start-position. Default values were used. 
STR$ TRU String truncation warning. The destination 


string could not contain all the characters copied 
from the source string. 


Condition Values Signaled 
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STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$POS EXTR 
could not allocate heap storage for a dynamic or 
temporary string. 
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STR$PREFIX 
Prefix a String 


Format 


Returns 


Arguments 


Description 


The Prefix a String routine inserts a source string at the beginning of a 
destination string. The destination string must be dynamic or varying length. 


STR$PREFIX _destination-string ,source-string 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string (dynamic or varying length). STR$PREFIX copies the source 
string into the beginning of this destination string. The destination-string 
argument is the address of a descriptor pointing to the destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string that STR$PREFIX copies into the beginning of the destination 
string. The source-string argument is the address of a descriptor pointing to the 
source string. 


STR$PREFIX inserts the source string at the beginning of the destination string. 
The destination string must be dynamic or varying length. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

STR$ TRU String truncation warning. The destination 
string could not contain all of the characters in 
the result. 
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Condition Values Signaled 


Example 
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STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


10 !+ 


Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$PREFIX 
could not allocate heap storage for a dynamic or 
temporary string. 


! This example uses STRSPREFIX to 
! prefix a destination string (D$) 
! with a source string (’ABCD’). 


!- 


EXTERNAL INTEGER 
DS = 'EFG’ 


STATUS% = STRSPRE 
PRINT DS 
END 


FUNCTION STRSPREFIX 


FIX (DS, ‘ABCD’) 


These BASIC statements set D$ equal to 'ABCDEFG’. 
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STR$RECIP 
Reciprocal of a Decimal String 


The Reciprocal of a Decimal String routine takes the reciprocal of the first decimal 
string to the precision limit specified by the second decimal string and returns 
the result as a decimal string. 


Format 
STR$RECIP  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign ,cexp ,cdigits 
Returns 
OpenVMS usage: cond_value 
type longword (unsigned) 
access: write only 
mechanism: by value 
Arguments 
asign 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Sign of the first operand. The asign argument is the address of an unsigned 
longword containing the first operand'’s sign. A value of 0 is considered positive; a 
value of 1 is considered negative. 


aexp 
OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which adigjits is multiplied to get the absolute value of the first 
operand. The aexp argument is the address of a signed longword containing this 


exponent. 

adigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


First operand’s numeric text string. The adigits argument is the address of a 
descriptor pointing to the first operand’s numeric string. The string must be an 
unsigned decimal number. 


bsign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
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Sign of the second operand. The bsign argument is the address of an unsigned 
longword containing the sign of the second operand. A value of 0 is considered 
positive; a value of 1 is considered negative. 


bexp 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Power of 10 by which bdigits is multiplied to get the absolute value of the second 
operand. The bexp argument is the address of a signed longword containing this 
exponent. 


bdigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Second operand’s numeric text string. The bdigits argument is the address of a 
descriptor pointing to the second operand’s numeric string. The string must be an 
unsigned decimal number. 


csign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Sign of the result. The csign argument is the address of an unsigned longword 
containing the result’s sign. A value of 0 is considered positive; a value of 1 is 
considered negative. 


cexp 
OpenVMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 


Power of 10 by which cdigjts is multiplied to get the absolute value of the result. 
The cexp argument is the address of a signed longword containing this exponent. 


cdigits 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Result’s numeric text string. The cdigits argument is the address of a descriptor 
pointing to the result’s numeric string. The string is an unsigned decimal 
number. 


Description 
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STR$RECIP takes the reciprocal of the first decimal string to the precision limit 
specified by the second decimal string and returns the result as a decimal string. 


Condition Values Returned 


SS$ NORMAL 
STR$ TRU 


Condition Values Signaled 


LIB$_INVARG 
STR$ DIVBY_ZER 
STR$ FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


STR$_WRONUMARG 


Example 


100 !+ 


Routine successfully completed. 


String truncation warning. The destination 
string could not contain all of the characters in 
the result. 


Invalid argument. 
Division by zero. 


Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$RECIP could 
not allocate heap storage for a dynamic or 
temporary string. 

Wrong number of arguments. 


! This example program uses STRSRECIP to find the reciprocal of the 
! first decimal string (A) to the precision specified in the second 
! decimal string (B), and place the result in a third decimal string (C). 


pe 
ASIGN’s = 1% 
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STRSRECIP 


"; ASIGN%; AEXP%; ADIGITS$ 
"; BSIGN%; BEXP%; BDIGITS$ 
(ASIGNS, AEXP%, ADIGITS$, & 


CSIGN%, CEXP%, CDIGITS$) 
PRINT "C = "; CSIGN%S; CEXP%; CDIGITSS 


999 END 


BSIGN%, BEXP%, BDIGITSS, & 
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This BASIC example uses STR$RECIP to find the reciprocal of A to the precision 
level specified in B, using the following values: 


A =-1000 (ASIGN =1, AEXP =3, ADIGITS ='17) 
B =.0002 (BSIGN =0, BEXP =-4, BDIGITS ='27) 


The output generated is as follows, yielding a decimal value of C equal to -.001: 


A 
B 
C 


1 31 
0 -4 2 
Li =3x41 
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STR$REPLACE 
Replace a Substring 


Format 


The Replace a Substring routine copies a source string to a destination string, 
replacing part of the string with another string. The substring to be replaced is 
specified by its starting and ending positions. 


STR$REPLACE  destination-string ,source-string ,start-position ,end-position 
,replacement-string 


Corresponding JSB Entry Point 


Returns 


Arguments 


STRSREPLACE_R8 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$REPLACE writes the new string created when 
it replaces the substring. The destination-string argument is the address of a 
descriptor pointing to the destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string. The source-string argument is the address of a descriptor 
pointing to the source string. 


start-position 
OpenVMS usage: longword_signed 


type: longword (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 


Position in the source string at which the substring that STR$REPLACE replaces 
begins. The start-position argument is the address of a signed longword 
containing the starting position. The position is relative to the start of the source 
string. 
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STR$REPLACE 
end-position 
OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference for CALL entry point, by value for J SB entry 


Description 


point 


Position in the source string at which the substring that STR$REPLACE replaces 
ends. The end-position argument is the address of a signed longword containing 
the ending position. The position is relative to the start of the source string. 


replacement-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Replacement string with which STR$REPLACE replaces the substring. The 
replacement-string argument is the address of a descriptor pointing to 
this replacement string. The value of replacement-string must be equal to 
end-position minus start-position. 


STR$REPLACE copies a source string to a destination string, replacing part of 
the string with another string. The substring to be replaced is specified by its 
starting and ending positions. 


If the starting position is less than 1, 1 is used. If the ending position is greater 
than the length of the source string, the length of the source string is used. If the 
starting position is greater than the ending position, the overlapping portion of 
the source string will be copied twice. 


Condition Values Returned 
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SS$ NORMAL Normal successful completion. 


STR$_ILLSTRPOS Alternate success. An argument referenced a 
character position outside the specified string. A 
default value was used. 


STR$ ILLSTRSPE Alternate success. The value of end-position 
was less than the value of start-position or 
the length of the substring was too long for the 
specified string. Default values were used. 


STR$ TRU String truncation warning. The destination 
string could not contain all of the characters. 


Condition Values Signaled 


Example 


STR$_FATINTERR 


LIB$_ INVARG 
STR$_ILLSTRCLA 


STR$_INSVIRMEM 
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Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

Invalid argument. 

IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STR$REPLACE 
could not allocate heap storage for a dynamic or 
temporary string. 


! This example uses STRSREPLACE to 
replace all characters from the starting 


i} 
! position (2%) to the 
! with characters fron 
1 (7 XYZ"). 

1 


ending position (3%) 
the replacement string 


EXTERNAL INTEGER FUNCTION STRSREPLACE 


STATUS% = STRSREPLACE (DS, DS, 2%, 3%, "XYZ’) 


DS = 'ABCD’ 
PRINT DS$ 
END 


These BASIC statements set D$ equal to ’AXYZD’. 
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STR$RIGHT 
Extract a Substring of a String 


Format 


The Extract a Substring of a String routine copies a substring ending at the last 
character of a source string into a destination string. 


STR$RIGHT  destination-string ,source-string ,start-position 


Corresponding JSB Eniry Point 


Returns 


Arguments 
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STR$RIGHT_R8 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$RIGHT copies the substring. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string from which STR$RIGHT extracts the substring that it copies 
into the destination string. The source-string argument is the address of a 
descriptor pointing to the source string. 


start-position 
OpenVMS usage: longword_signed 


type: longword (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for J SB entry 
point 


Relative position in the source string at which the substring that STR$RIGHT 
copies starts. The start-position argument is the address of a signed longword 
containing the starting position. 
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Description 


STR$RIGHT extracts a substring from a source string and copies that substring 
into a destination string. STR$RIGHT defines the substring by specifying the 
relative starting position. The relative ending position is equal to the length of 
the source string. The source string is unchanged, unless it is also the destination 
string. 


If the starting position is less than 2, the entire source string is copied. If the 
starting position is greater than the length of the source string, a null string is 
copied. 


This is a variation of STR$POS_EXTR. Other routines that can be used to extract 
and copy a substring are STR$LEFT and STR$LEN_EXTR. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


STR$_ILLSTRPOS Alternate success. An argument referenced a 
character position outside the specified string. A 
default value was used. 

STR$ TRU String truncation warning. The destination 
string could not contain all the characters copied 
from the source string. 


Condition Values Signaled 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

LIB$ INVARG Invalid argument. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$RIGHT could 
not allocate heap storage for a dynamic or 
temporary string. 


Example 


PROGRAM RIGHT(INPUT, OUTPUT); 


+} 
This example uses STRSRIGHT to extract a substring 
from a specified starting position (START_POS) to 
the end (right side) of a source string (SRC_STR) 
and write the result in a destination string (DST_STR). 


First, declare the external procedure. 
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PROCEDURE STRSRIGHT(%DESCR DSTSTR: VARYING 
[A] OF CHAR; SRCSTR : VARYING [B] OF CHAR; 
STARTPOS : INTEGER); EXTERN; 


{ Declare the variables used in the main program. 


VAR 
SRC_STR : VARYING [256] OF CHAR; 
DST_STR : VARYING [256] OF CHAR; 
START_POS : INTEGER; 


{ 
{ Begin the main program. Read the source string 
{ and starting position. Call STRSRIGHT to extract 
{ the substring. Print the result. 

{ 


RITELN(’ENTER THE SOURCE STRING: '); 
READLN (SRC_STR) ; 

RITELN (’ENTER THE STARTING POSITION’ ) ; 
RITELN ('OF THE SUBSTRING: '); 

EADLN (START_POS) ; 

TRSRIGHT (DST_STR, SRC_STR, START_POS); 
RIT : 

R 


ELN; 
ITELN(’THE SUBSTRING IS: '’,DST_STR); 


peo) 


EN 


This Pascal program uses STR$RIGHT to extract a substring from a specified 
starting position (START POS) to the end of the source string. One sample of the 
output is as follows: 


$ RUN RIGHT 

ENTER THE SOURCE STRING: BLUE PLANETS ALWAYS HAVE PURPLE PLANTS 
ENTER THE STARTING POSITION 

OF THE SUBSTRING: 27 

THE SUBSTRING IS: URPLE PLANTS 
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STR$SROUND 
Round or Truncate a Decimal String 


The Round or Truncate a Decimal String routine rounds or truncates a decimal 
string to a specified number of significant digits and places the result in another 
decimal string. 


Format 
STR$ROUND places ,flags ,asign ,aexp ,adigits ,csign ,cexp ,cdigits 
Returns 
OpenVMS usage: cond_value 
type longword (unsigned) 
access: write only 
mechanism: by value 
Arguments 
places 
OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 


Maximum number of decimal digits that STR$ROUND retains in the result. The 
places argument is the address of a signed longword containing the number of 
decimal digits. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Function flag. A value of 0 indicates that the decimal string is rounded; a value of 
1 indicates that it is truncated. The flags argument is the address of an unsigned 
longword containing this function flag. 


asign 

OpenVMS usage: longword_unsigned 
type longword (unsigned) 
access: read only 
mechanism: by reference 


Sign of the decimal input string to be rounded or truncated. The asign argument 
is the address of an unsigned longword string containing this sign. A value of 0 
is considered positive; a value of 1 is considered negative. 


aexp 
OpenVMS usage: longword_signed 
type longword (signed) 
access: read only 
mechanism: by reference 
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Power of 10 by which adigjits is multiplied to get the absolute value of the 
decimal input string. The aexp argument is the address of a signed longword 
containing this exponent. 


adigits 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Decimal input string. This is the string of digits to which asign and aexp are 
applied. The adigits argument is the address of a descriptor pointing to this 
numeric string. The string must be an unsigned decimal number. 


csign 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Sign of the result. The csign argument is the address of an unsigned longword 
containing the result’s sign. A value of 0 is considered positive; a value of 1 is 
considered negative. 


cexp 
OpenVMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 


Power of 10 by which cdigjts is multiplied to get the absolute value of the result. 
The cexp argument is the address of a signed longword containing this exponent. 


cdigits 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Result’s numeric text string. The cdigits argument is the address of a descriptor 
pointing to this numeric string. The string is an unsigned decimal number. 
Description 


The Round or Truncate a Decimal String routine rounds or truncates a decimal 
string to a specified number of significant digits and places the result in another 
decimal string. 


Condition Values Returned 
SS$ NORMAL Normal successful completion. 


STR$ TRU String truncation warning. The destination 
string could not contain all of the characters. 
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Condition Values Signaled 


Example 


LIB$_INVARG 


STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


STR$_WRONUMARG 


Invalid argument. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 
Insufficient virtual memory. STRSROUND 
could not allocate heap storage for a dynamic or 
temporary string. 

Wrong number of arguments. 


100 !+ 


! This example shows the difference between the values obtained 
! when rounding or truncating a decimal string. 

= 

ASIGNS = 0 

AEXPS = -4% 
ADIGITS$ = '9999998' 
CSIGNS = 0 

CEXP%S = 0% 

CDIGITSS 

PRINT "A 


ro’ 
"; ASIGNS; AEXP%S; ADIGITSS 


! First, call STRSROUND to round the value of A. 


CALL STRSROUND (3%, 0%, ASIGN%, AEXP%, ADIGITSS, & 
CSIGN%, CEXP%, CDIGITS$) 
PRINT "ROUNDED: C = "; CSIGN%; CEXP%; CDIGITS$ 


! ow, call STRSROUND to truncate the value of A. 


CALL STRSROUND (3%, 1%, ASIGNS, AEXP%, ADIGITSS, & 
CSIGN%, CEXP%, CDIGITS$) 

PRINT "TRUNCATED: C = "; CSIGN%; CEXP%; CDIGITS$ 
999 END 


This BASIC example uses STR$ROUND to round and truncate the value of A to 
the number of decimal places specified by places. The following values apply: 


A = 999.9998 (ASIGN = 0, AEXP = --4, ADIGITS = '9999998") 


The output generated by this program is as follows; note that the decimal value 


of C equals 1000 when rounded and 999 when truncated. 


A= 0 -4 9999998 
ROUNDED: C = 0 1 100 
TRUNCATED: C = 0 0 999 
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STR$STRANSLATE 
Translate Matched Characters 


Format 


Returns 


Arguments 


STR-86 


The Translate Matched Characters routine successively compares each character 
in a source string to all characters in a match string. If a source character has a 
match, the destination character is taken from the translate string. Otherwise, 


STR$TRANSLATE moves the source character to the destination string. 


STR$TRANSLATE  destination-string ,source-string ,translation-string ,match-string 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string. The destination-string argument is the address of a 
descriptor pointing to the destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string. The source-string argument is the address of a descriptor 
pointing to the source string. 


translation-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Translate string. The translation-string argument is the address of a descriptor 


pointing to the translate string. 


match-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Match string. The match-string argument is the address of a descriptor pointing 


to the match string. 


Description 


STR$ Routines 
STR$TRANSLATE 


STR$TRANSLATE successively compares each character in a source string 

to all characters in a match string. If a source character matches any of the 
characters in the match string, STR$TRANSLATE moves a character from the 
translate string to the destination string. Otherwise, STR$TRANSLATE moves 
the character from the source string to the destination string. 


The character taken from the translate string has the same relative position 

as the matching character had in the match string. When a character appears 
more than once in the match string, the position of the leftmost occurrence of 
the multiply-defined character is used to select the translate string character. If 
the translate string is shorter than the match string and the matched character 
position is greater than the translate string length, the destination character is a 
space. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


STR$ TRU String truncation warning. The destination 
string could not contain all of the characters. 


Condition Values Signaled 


Example 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 


STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ INSVIRMEM Insufficient virtual memory. STR$TRANSLATE 
could not allocate heap storage for a dynamic or 
temporary string. 


10 V+ 

This example program uses STRSTRANSLATE to 
translate all characters of a source string 
from uppercase to lowercase characters. 


EXTERNAL INTEGER FUNCTION STRSTRANSLATE (STRING, STRING, STRING, STRING) 
TOS=’ abcdefghijklmnopaqrstuvwxyz’ 

FROMS=’ ABCDEFGHIJKLMNOPQRSTUVWXY2’ 

X% = STRSTRANSLATE (OUTS, ’ TEST’, TOS, FROMS) 


PRINT 'Status = ';x% 
PRINT 'Resulting string = ';out$ 
32767 END 


This BASIC example translates uppercase letters to lowercase letters, thus 
performing a function similar to but the opposite of STR$UPCASE. 
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The output generated by this example is as follows: 


S$ RUN TRANSLATE 
Status = 1 
Resulting string = test 


A more practical although more complicated use for STR$TRANSLATE is to 
encrypt data by translating the characters to obscure combinations of numbers 
and alphabetic characters. 
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STR$TRIM 


Trim Trailing Blanks and Tabs 


Format 


Returns 


Arguments 


The Trim Trailing Blanks and Tabs routine copies a source string to a destination 
string and deletes the trailing blank and tab characters. 


STR$TRIM _ destination-string ,source-string [,resultant-length] 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$TRIM copies the trimmed string. The 
destination-string argument is the address of a descriptor pointing to the 
destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string which STR$TRIM trims and then copies into the destination string. 
The source-string argument is the address of a descriptor pointing to the source 
string. 


resultant-length 
OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: write only 
mechanism: by reference 


Number of bytes that STR$TRIM writes into destination-string, not counting 
padding in the case of a fixed-length string. The resultant-length argument 

is the address of an unsigned word into which STR$TRIM writes the length of 
the output string. If the input string is truncated to the size specified in the 
destination-string description, resultant-length is set to this size. Therefore, 
resultant-length can always be used by the calling program to access a valid 
substring of destination-string. 
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Description 


STR$TRIM copies a source string to a destination string and deletes the trailing 
blank and tab characters. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


STR$ TRU String truncation warning. The destination 
string could not contain all the characters. 


Condition Values Signaled 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 

STR$ ILLSTRCLA Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 

STR$ INSVIRMEM Insufficient virtual memory. STR$TRIM could 
not allocate heap storage for a dynamic or 
temporary string. 
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STR$UPCASE 
Convert String to All Uppercase Characters 


Format 


Returns 


Arguments 


Description 


The Convert String to All Uppercase Characters routine converts a source string 
to uppercase. 


STR$UPCASE destination-string ,source-string 


OpenVMS usage: cond_value 


type longword (unsigned) 
access: write only 
mechanism: by value 


destination-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Destination string into which STR$UPCASE writes the string it has converted 
to uppercase. The destination-string argument is the address of a descriptor 
pointing to the destination string. 


source-string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Source string that STR$UPCASE converts to uppercase. The source-string 
argument is the address of a descriptor pointing to the source string. 


STR$UPCASE converts successive characters in a source string to uppercase and 
writes the converted character into the destination string. The routine converts 
all characters in the DEC Multinational Character Set. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


STR$ TRU String truncation warning. The destination 
string could not contain all the characters. 
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Condition Values Signaled 


STR$ FATINTERR Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to your Compaq support 
representative. 


STR$ ILLSTRCLA IIlegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the OpenVMS calling standard. 


STR$ INSVIRMEM Insufficient virtual memory. STR$UPCASE 
could not allocate heap storage for a dynamic or 
temporary string. 


Example 
30) }+ 
! This example uses STRSUPCASE 
! to convert all characters in 
! the source string (SRC$) to 
! uppercase and write the result 
! in the destination string (DSTS$). 
! 


SRCS = ‘abcd’ 

PRINT "SRCS =";SRCS$ 

CALL STRSUPCASE (DST$, SRC$) 
PRINT "DSTS =";DSTS 

END 


This BASIC program generates the following output: 


SCRS =abcd 
DSTS =ABCD 
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comparing for equality, no padding, STR-17 


comparing two, STR-15 
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